pypaperless
pypaperless is a modern, fully async Python client library for the Paperless-ngx REST API.
Features
| Feature | Details |
|---|---|
| Fully async | Built on asyncio + httpx.AsyncClient; drop-in for any async framework |
| Type-safe models | All resources are validated Pydantic models |
| Complete resource coverage | Documents, Correspondents, Tags, Document Types, Storage Paths, Custom Fields, Saved Views, Share Links, Workflows, Mail Accounts/Rules, Tasks, Trash, and more |
| CRUD + permissions | Create, read, update, delete and manage object-level permissions per resource |
| Async iteration & paging | Iterate over all items or page-by-page; server-side filtering via filter() |
| Document operations | Upload, download, search (full-text & advanced), notes, suggestions, metadata |
| Custom field system | Rich typed access to custom field values — read, write, remove with caching |
| Token generation | Static helper to exchange username + password for an API token |
| Custom HTTP client | Bring your own httpx.AsyncClient for full control over timeouts, proxies, TLS, … |
Quick example
import asyncio
from pypaperless import PaperlessClient
async def main():
async with PaperlessClient("localhost:8000", "your-api-token") as paperless:
# iterate all documents - pagination is handled automatically
async for document in paperless.documents:
print(document.id, document.title)
# fetch a single item
doc = await paperless.documents(42)
# filter with server-side parameters
async with paperless.tags.filter(name__icontains="invoice") as filtered:
async for tag in filtered:
print(tag.id, tag.name)
asyncio.run(main())
Installation
Requires Python 3.13+.
pip install pypaperless
Documentation
Full documentation is available here.
Compatibility matrix
| pypaperless | Paperless-ngx | Python | Notes |
|---|---|---|---|
| >= v6.0 | >= 3.0 | 3.13 | Current release |
| >= v5.2 | >= 2.19 | 3.12 | |
| >= v5.0 | >= 2.17 | 3.12 | |
| >= v4.x | >= 2.15 | 3.12 | |
| < v4.0 | < 2.15 | 3.11 | Incompatible with Paperless-ngx >= 2.15 |
Recommendation: Keep both Paperless-ngx and pypaperless up to date to benefit from the latest API features and bug fixes.
Authors & contributors
pypaperless is written and maintained by Tobias Schulz. Feedback and contributions are always welcome.
Check out all contributors.