Dropbox Python SDK

The Backup and Restore sample demonstrates two primary workflows using the Dropbox API:

1. Backing up a file: Uploading a local file (e.g., my-file.txt) to Dropbox. This represents backing up app or user data.
2. Restoring a file: Using the /revisions endpoint to restore a file to a previous version.

The dropbox.async_ module provides asynchronous versions of the Dropbox SDK functionality.

Important Python Version Compatibility:

• Python 3.5+: You must import from dropbox.async_ because async is a reserved keyword.
• Python < 3.5: You can import from either dropbox.async or dropbox.async_.

# For Python 3.5 and newer
import dropbox.async_

Starting with version 12.0.0, the SDK no longer provides its own internal CA bundle for verifying TLS connections. Instead, it relies on the requests library, which uses the certifi package for certificate verification.

If you need to use a custom certificate bundle, you can still provide one using the ca_certs parameter in the Dropbox classes or the create_session function.

# Example of providing a custom CA bundle
# (Note: parameter availability depends on the specific Dropbox class used)
dropox_client = Dropbox(access_token, ca_certs='/path/to/your/cert_bundle.pem')

To use the official Dropbox SDK for Python, ensure you have Python 3.11 or newer installed. Older versions (including Python 2.7 and 3.4 through 3.10) are not supported.

Via pip

You can install the SDK directly from PyPI using pip:

$ pip install dropbox

From source

If you need to install from the repository source:

$ git clone git://github.com/dropbox/dropbox-sdk-python.git
$ cd dropbox-sdk-python
$ pip install .

Important Compatibility Note: You must use v12.0.2 or newer of this SDK to maintain compatibility with Dropbox API servers. Versions older than v12.0.2 stopped working in January 2026 due to API server certificate changes.

In version 11.0.0, the internal structure of the SDK was updated, resulting in the renaming of dropbox.dropbox to dropbox.dropbox_client.

• If you use direct imports like import dropbox.dropbox.foo, you must update them to import dropbox.dropbox_client.foo.
• If you use standard imports via the package root (e.g., from dropbox import Dropbox), your code will continue to work without changes because these imports are preserved in dropbox/__init__.py.

# OLD (v10.X.X)
import dropbox.dropbox
client = dropbox.dropbox.Dropbox()

# NEW (v11.0.0+)
import dropbox.dropbox_client
client = dropbox.dropbox_client.Dropbox()

# RECOMMENDED (Works in both)
from dropbox import Dropbox
client = Dropbox()

To run the Backup and Restore sample application, follow these steps:

1. Install the Dropbox Python SDK: Ensure the SDK is installed following the official installation instructions.
2. Configure your Access Token: Open backup-and-restore-sample.py and locate the TOKEN variable. Replace the empty string with your valid Dropbox access token:

   TOKEN = 'YOUR_ACCESS_TOKEN'

3. Execute the script: Navigate to the example/backup-and-restore directory and run the script using Python.

Upon successful execution, a file named my-file-backup.txt will appear in your Dropbox account.

python backup-and-restore-sample.py

The repository provides several example applications to demonstrate core SDK functionality. These are categorized into OAuth flows and general file operations:

OAuth Examples

• Commandline OAuth Basic: A simple commandline OAuth implementation without a redirect.
• Commandline OAuth Scopes: Demonstrates commandline OAuth using specific scopes.
• Commandline OAuth PKCE: Demonstrates commandline OAuth using the PKCE (Proof Key for Code Exchange) flow.

File Operation Examples

• Updown: A sample application that uploads the contents of your local Downloads folder to Dropbox.
• Backup and Restore: A sample application demonstrating how to backup a file and restore previous versions if a file is modified or corrupted.

Dropbox file properties are organized into PropertyGroup objects. A PropertyGroup is a subset of fields defined by a specific template_id. Properties are always added to a Dropbox file as a PropertyGroup.

Key components:

• template_id: A unique identifier for the associated template.
• fields: A list of PropertyField objects containing the actual property data.

To update properties on a file, use UpdatePropertiesArg which takes a path and a list of PropertyGroupUpdate objects to apply 'delta' updates.

# Example conceptual usage for updating properties
update_arg = UpdatePropertiesArg(
    path="/path/to/file.txt",
    update_property_groups=[
        PropertyGroupUpdate(
            template_id="your_template_id",
            add_or_update_fields=[PropertyField(name="key", value="value")]
        )
    ]
)