Install & Compatibility
Where this runs
tested against v4.7.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.735s · 30.2MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 3.8s · import 0.665s · 31MB
29MB installed
● package 29MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
DocumentCloud
✓ from documentcloud import DocumentCloud
✗ import documentcloud
The primary `DocumentCloud` client class is imported directly from the `documentcloud` package. The top-level `documentcloud` module itself is not typically imported as a whole.
APIError
✓ from documentcloud.exceptions import APIError
Common exceptions for API interactions are found within the `documentcloud.exceptions` submodule.
This quickstart demonstrates how to initialize the DocumentCloud client and perform a basic search for documents. Authentication is handled via environment variables (`DC_USERNAME`, `DC_PASSWORD`) for secure credential management. It then iterates through the search results and fetches a specific document by ID.
import os
from documentcloud import DocumentCloud
# Authenticate using environment variables for security
USERNAME = os.environ.get('DC_USERNAME', '')
PASSWORD = os.environ.get('DC_PASSWORD', '')
try:
# Initialize the client. For private documents/actions, provide credentials.
# For public documents, no credentials are required.
client = DocumentCloud(USERNAME, PASSWORD)
# Search for documents
query = 'MuckRock'
print(f"Searching for documents with query: '{query}'")
documents = client.documents.search(query)
if documents:
print(f"Found {len(documents)} documents:")
for doc in documents:
print(f" - ID: {doc.id}, Title: {doc.title}, Status: {doc.status}")
# Access a specific document by ID (replace with a real ID)
first_doc_id = documents[0].id
doc = client.documents.get(first_doc_id)
print(f"\nRetrieved document ID {doc.id}: '{doc.title}'")
print(f" Source: {doc.source}")
else:
print("No documents found for the given query.")
except Exception as e:
print(f"An error occurred: {e}")
print("Ensure DC_USERNAME and DC_PASSWORD environment variables are set if accessing private data.")
Debug
Known issues
breakingPython 2 support was dropped starting with version 4.0.0. Earlier versions (3.x and below) supported Python 2 and 3.fixEnsure your project runs on Python 3.8 or newer. Upgrade your Python environment if necessary.
affects: >=4.0.0
breakingThe API pagination mechanism changed from page number-based to cursor-based in version 3.0.0. This means the `__len__` method is no longer implemented for `APIResults`, and you cannot randomly access pages by number. Iteration is the primary method for processing results.fixIterate through API results directly or use cursor parameters for paging. Avoid relying on `len()` for result sets or direct page number access.
affects: >=3.0.0
gotchaThe PyPI package `documentcloud` (without the 'python-' prefix) is deprecated and refers to an older, unmaintained version of the library. Installing this package will lead to outdated functionality and potential compatibility issues.fixAlways install `python-documentcloud` via `pip install python-documentcloud`. If `documentcloud` is already installed, uninstall it first: `pip uninstall documentcloud`.
affects: All versions, if wrong package is installed
gotchaWhen uploading a new document, its status will initially be 'pending' or 'private' even if marked 'public', due to server-side processing. Attempts to interact with full metadata or public status immediately after upload may show stale data.fixAfter uploading, periodically call `document.refresh()` and check `document.status` and `document.public` in a loop until the document is fully processed and reflects the intended status.
affects: All versions
Errors
Common errors & fixes
ImportError: cannot import name 'DocumentCloud' from 'documentcloud'
This typically occurs because the deprecated `documentcloud` PyPI package was installed instead of the correct `python-documentcloud` package, or a mix-up in import paths.
fixFirst, uninstall the incorrect package: `pip uninstall documentcloud`. Then, install the correct one: `pip install python-documentcloud`. Ensure your import statement is `from documentcloud import DocumentCloud`.
documentcloud.exceptions.CredentialsFailedError: Unable to obtain an access token due to bad login credentials
The username or password provided to the `DocumentCloud` client constructor (or via environment variables) is incorrect or lacks the necessary permissions.
fixVerify that your `DC_USERNAME` and `DC_PASSWORD` environment variables are correctly set, or that the credentials passed directly to `DocumentCloud()` are accurate for a valid DocumentCloud account with API access.
documentcloud.exceptions.MultipleObjectsReturnedError: The API returned multiple objects when it expected one
You used a method or query that expects a single, unique result (e.g., `client.documents.get(id)`) but multiple items matched the criteria, or the identifier was not specific enough.
fixEnsure that the identifier used is truly unique (e.g., a DocumentCloud numerical ID). If searching, use `client.documents.search()` which is designed to return multiple results, and then process the list.
documentcloud.exceptions.DoesNotExistError
Attempted to access a document, project, or other resource that either does not exist, or the authenticated user does not have permission to view.
fixDouble-check the ID or slug of the resource you are trying to access. Confirm that your DocumentCloud account has the necessary permissions to view or modify that specific resource.
Upgrade
Version history
4.7.0latest on PyPI · released Jun 15, 2026
Audit
Dependencies
No dependency data recorded yet.