pypaperless is a modern, fully async Python client library for the Paperless-ngx REST API.
| 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, … |
import asyncio
from pypaperless import Paperless
async def main():
async with Paperless("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 for tag in paperless.tags.filter(name__icontains="invoice"):
print(tag.id, tag.name)
asyncio.run(main())Requires Python 3.13+.
pip install pypaperlessFull documentation is available here.
| 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.
pypaperless is written and maintained by Tobias Schulz. Feedback and contributions are always welcome.
Check out all contributors.
