Skip to main content

Tahoe-LAFS-based file synchronization

Project description

Magic Folder

This repository is provisional. It may move to a different organization.

Magic Folder for Tahoe-LAFS is a Free and Open file synchronization system. It detects local changes to files and uploads those changes to a Tahoe-LAFS grid. It monitors a Tahoe-LAFS grid and downloads changes to the local filesystem.

documentation status gha_linux gha_macos gha_windows test coverage percentage


for integrators

When packaging magic-folder, please install using our pinned requirements, which are tested in CI. This should be done in a virtualenv, or other isolated python environment, so as to not interfere with system or user python packages:

git clone
cd magic-folder
pip install --require-hashes -r requirements/base.txt
pip install --no-deps .

from source

To install from source (either so you can hack on it, or just to run pre-release code), you should create a virtualenv and install into that:

git clone
cd magic-folder
virtualenv venv
venv/bin/pip install --upgrade setuptools
venv/bin/pip install --editable .
venv/bin/magic-folder --version


Magic-Folder is configured via the magic-folder command-line tool.

Magic-Folder configuration is kept in a directory. The default place for this directory is platform-dependant; on Linux it will be in ~/.config/magic-folder. Inside this directory is a database for global configuration and sub-directories to track state and temporary space for each actual magic-folder including a configuration database. All databases are SQLite.

A running Magic-Folder needs to have access to a Tahoe-LAFS client that it may use to perform operations in the Tahoe-LAFS Grid. This is referenced by the “node directory” of the Tahoe-LAFS client although actual operations are performed via the Tahoe-LAFS WebUI.

There are two ways to create a new Magic Folder instance (that is, the configuration required). Create a fresh one with magic-folder create or migrate from a Tahoe-LAFS 1.14.0 or earlier instance with magic-folder migrate.

Once a Magic-Folder is configured, functionality is provided by running a long-lived magic-folder daemon. This process is run using the magic-folder command line tool:

magic-folder --config <path to Magic Foler directory> run

As long as this process is running, whatever magic folders are configured will be functional. The process must be restarted to read configuration changes. All other interactions are via the HTTP API which listens on a local endpoint according to the configuration. Other magic-folder subcommands are typically just thin CLI wrappers around a particular HTTP endpoint.


To run the unit test suite:

  • tox

You can pass arguments to trial with an environment variable. For example, you can run the test suite on multiple cores to speed it up:



Documentation is written as reStructuredText documents and processed using Sphinx; you will need sphinx and sphinx_rtd_theme. To generate HTML version of Magic Folder documents, do:

  • cd docs; make html

Resulting HTML files will be under docs/_build/html/.


Copyright 2006-2018 The Tahoe-LAFS Software Foundation Copyright 2020-2021 The Magic-Folder Developers

You may use this package under the GNU General Public License, version 2 or, at your option, any later version. You may use this package under the Transitive Grace Period Public Licence, version 1.0, or at your option, any later version. (You may choose to use this package under the terms of either licence, at your option.) See the file COPYING.GPL for the terms of the GNU General Public License, version 2. See the file COPYING.TGPPL for the terms of the Transitive Grace Period Public Licence, version 1.0.

See TGPPL.PDF for why the TGPPL exists, graphically illustrated on three slides.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

magic-folder-24.3.0.tar.gz (4.5 MB view hashes)

Uploaded Source

Built Distribution

magic_folder-24.3.0-py3-none-any.whl (270.6 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page