Dropbox API Client

12.0.2 · active · verified Thu Apr 09

The official Dropbox API Client for Python (v12.0.2) allows programmatic interaction with Dropbox services. It provides a comprehensive interface for file management, sharing, user account information, and more. The library maintains an active development cycle, with frequent updates often driven by API specification changes.

Common errors

```
ModuleNotFoundError: No module named 'dropbox'
```
cause This error occurs when the `dropbox` library is not installed in the Python environment being used, or the environment's `PYTHONPATH` does not include the installation location, or there are multiple Python versions/environments, and it was installed in a different one.

fix Ensure the library is installed in the correct environment using `pip install dropbox`. If multiple Python versions exist, specify the interpreter (e.g., `python3 -m pip install dropbox`).
```
AttributeError: module 'dropbox' has no attribute 'Dropbox'
```
cause This error most commonly happens when the Python script itself is named `dropbox.py`. When `import dropbox` is called, Python imports the local file instead of the installed library, and the local file does not contain the `Dropbox` class.

fix Rename your Python script to something other than `dropbox.py` (e.g., `my_dropbox_app.py`) and delete any `dropbox.pyc` file in the same directory.
```
dropbox.exceptions.AuthError: AuthError('invalid_access_token', None)
```
cause This error indicates that the provided access token is expired, revoked, malformed, or lacks the necessary permissions (scopes) for the attempted operation. Dropbox now uses short-lived tokens and refresh tokens, requiring a refresh mechanism for long-term access.

fix Obtain a new access token. If using offline access, ensure you are storing and correctly using a refresh token to generate new short-lived access tokens before they expire. Verify that the app's permissions (scopes) in the Dropbox App Console match the API calls being made.
```
dropbox.exceptions.ApiError: ApiError(..., LookupError('not_found', None))
```
cause This specific `ApiError` (often showing 'path/not_found') means that the file or folder path specified in the API call does not exist in the connected Dropbox account, or there is a typo in the path, or the app lacks access to that particular path due to its access type (e.g., 'app folder' vs 'full Dropbox').

fix Double-check the exact path on Dropbox. Ensure the app has the correct access type configured in the Dropbox App Console ('App folder' apps can only access files within their dedicated app folder). Use `dbx.files_list_folder('')` to verify paths from the root if unsure.

Warnings

breaking Starting with v12.0.0, the SDK no longer provides a hardcoded CA bundle. If your environment requires specific SSL certificate handling or you relied on the internal bundle, you may need to explicitly provide a `ca_certs` argument to the `Dropbox` client.
Fix: For specific SSL needs, provide your CA certificate path: `dbx = dropbox.Dropbox(token, ca_certs='/path/to/your/ca.pem')`
gotcha Versions prior to v12.0.2 had incorrect or overly strict dependency pinning for `requests` and `urllib3`, which could lead to conflicts with other libraries in your environment. These issues were resolved in v12.0.2.
Fix: Upgrade to `dropbox==12.0.2` or later to resolve potential dependency conflicts.
gotcha The `dropbox.Dropbox` client constructor expects a long-lived 'access token' (e.g., for OAuth2 or personal apps), not a short-lived 'authorization code'. Attempting to use an authorization code directly will result in an `AuthError`.
Fix: Ensure you are using a generated access token (e.g., from the Dropbox App Console or obtained via the OAuth flow after exchanging a code) when initializing the client. Store it securely, preferably in an environment variable.

Install

pip install dropbox Install stable version

Imports

Dropbox

import dropbox
dbx = dropbox.Dropbox(...)

AuthError

from dropbox.exceptions import AuthError

ApiError
```
from dropbox.exceptions import ApiError
```

Quickstart

This quickstart demonstrates how to authenticate with the Dropbox API using an access token loaded from the `DROPBOX_ACCESS_TOKEN` environment variable and then list the contents of your Dropbox root folder.

import os
import dropbox
from dropbox.exceptions import AuthError, ApiError

DROPBOX_ACCESS_TOKEN = os.environ.get('DROPBOX_ACCESS_TOKEN', '')

if not DROPBOX_ACCESS_TOKEN:
    print("Error: DROPBOX_ACCESS_TOKEN environment variable not set.")
    print("Please set it to your Dropbox API access token.")
    exit(1)

try:
    # Initialize Dropbox client
    dbx = dropbox.Dropbox(DROPBOX_ACCESS_TOKEN)

    # Test connection by listing files in the root folder
    print("\nConnected to Dropbox. Listing root folder content...")
    response = dbx.files_list_folder('')
    
    for entry in response.entries:
        print(f"  {entry.name} ({type(entry).__name__})")

    print("\nSuccessfully listed folder content.")

except AuthError:
    print("Error: Invalid or expired access token. Please check DROPBOX_ACCESS_TOKEN.")
except ApiError as err:
    print(f"API Error: {err}")
except Exception as err:
    print(f"An unexpected error occurred: {err}")

view raw JSON →