DOCSEARCHbyAlgolia
Submit Docs

Maestral Documentation

repository·main·Indexed 25 days ago

https://github.com/samschott/maestral

An open-source Dropbox client for macOS and Linux written in Python. Maestral provides syncing capabilities for platforms and file systems no longer supported by the official Dropbox client, featuring a CLI, GUI support, and the ability to sync multiple accounts. The documentation covers installation via Homebrew, PyPI, and Docker, as well as detailed technical references for its SyncEngine, configuration files, state management, and conflict resolution logic.

Tokens
18K
Snippets
20
Records
152
Agent score
85%

What's inside Maestral

  2. Initialize and link a Maestral instance in Python

    main

    To use the Maestral API programmatically, import the Maestral class from maestral.main. You must initialize the instance with a config_name. If the configuration name does not exist, config and state files will be created on-demand.

    To connect to a Dropbox account, use the following workflow:

    1. Call get_auth_url() to generate a Dropbox OAuth2 PKCE authorization URL.
    2. Prompt the user to visit the URL and provide the resulting authorization token.
    3. Call link(token) with the provided token to exchange it for an access token. The credentials are then saved in the system keyring (e.g., macOS Keychain or Gnome Keyring).

    The link method returns:

    • 0: Success
    • 1: Invalid code
    • 2: Connection error
    from maestral.main import Maestral

# Initialize with a configuration name
m = Maestral(config_name="private")

# OAuth2 flow
url = m.get_auth_url()
print(f"Please go to {url} to retrieve a Dropbox authorization token.")
token = input("Enter auth token: ")
res = m.link(token)

# Handle linking result and start syncing
if res == 0:
    m.create_dropbox_directory("~/Dropbox (Private)")
    m.start_sync()

  3. Install Maestral via PyPI

    main

    It is recommended to install Maestral within a Python virtual environment.

    To install the standard version:

    $ python3 -m venv maestral-venv
$ source maestral-venv/bin/activate
(maestral-venv)$ python3 -m pip install --upgrade maestral

    To install with Graphical User Interface (GUI) support (installs maestral-qt and PyQt5 on Linux, or maestral-cocoa on macOS):

    (maestral-venv)$ python3 -m pip install --upgrade 'maestral[gui]'
    $ python3 -m venv maestral-venv
$ source maestral-venv/bin/activate
(maestral-venv)$ python3 -m pip install --upgrade 'maestral[gui]'

  4. Sync multiple Dropbox accounts

    main

    You can run multiple instances of Maestral to sync different Dropbox accounts by using the --config-name option with start or gui. This creates or selects a specific configuration file for that instance.

    To list all currently linked accounts and their configuration files, use maestral config-files.

    $ maestral start --config-name="personal"
$ maestral start --config-name="work"

$ maestral config-files

  5. Modify path and excluded_items settings

    main

    Do not edit the path or excluded_items values manually in the configuration file. Changing these values requires Maestral to perform specific actions (such as moving the local Dropbox directory or downloading items removed from an exclusion list) that manual edits will not trigger.

    Instead, use the corresponding CLI commands or GUI options to modify these settings.

  10. Initialize logging with setup_logging()

    main

    Use setup_logging() to configure logging for a specific Maestral configuration. This function sets up loggers scoped to the provided config_name and can route logs to files, stderr, the systemd journal, and systemd status notifications. It automatically determines the log level from the Maestral configuration.

    Parameters:

    • config_name (str): The name of the configuration to use for scoping and log level retrieval.
    • file (bool): If True, logs to a file using RotatingFileHandler (default: True).
    • stderr (bool): If True, logs to stderr (default: True).
    • journal (bool): If True, logs to the systemd journal if running in a systemd environment (default: True).
    • status (bool): If True, sends INFO level messages to the systemd status notifier via SdNotificationHandler (default: True).

    Returns:

    • A Sequence[logging.Handler] containing the created handlers.

  11. Link a Dropbox account with DropboxClient

    main

    To link a Dropbox account, follow these steps:

    1. Call get_auth_url() to obtain a URL.
    2. The user visits the URL and retrieves an authorization code.
    3. Call link(code=...) with that code to exchange it for tokens, which are then stored in the provided CredentialStorage.

    Alternatively, you can link directly using a refresh_token or access_token via the link method.

  12. Initialize and use the Maestral client

    main

    The Maestral class is the primary public API for interacting with Dropbox. You can create an instance with a specific config_name to manage multiple Dropbox accounts. To link an account, use get_auth_url() to obtain an authorization URL, then pass the resulting token to link(). Once linked, you can set up a local directory and start the sync process.

    Note: Maestral currently only supports macOS and Linux.

    from maestral.main import Maestral

# Create a new configuration named 'private'
m = Maestral(config_name='private')

# Get the URL to authorize access
url = m.get_auth_url()
print(f'Please go to {url} to retrieve a Dropbox authorization token.')

# Enter the token from the website
token = input('Enter auth token: ')

# Link the account
res = m.link(token)
if res == 0:
    # Set up the local Dropbox folder and start syncing
    m.create_dropbox_directory('~/Dropbox (Private)')
    m.start_sync()