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 | generate_api_token() 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 |
Authors & contributors
pypaperless is written and maintained by: Tobias Schulz and Claude. Feedback and contributions are always welcome.
Check out all contributors.
1 maintainer
Metadata
1 maintainer
Release files for pypaperless 6.0.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| pypaperless-6.0.2.tar.gz | 275.5 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| pypaperless-6.0.2-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 385.5 kB
Release files / pypaperless-6.0.2.tar.gz
| Download URL | pypaperless-6.0.2.tar.gz |
|---|---|
| Size | 275.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
65b420a9254fb611b0b5300582b9954274659ab44594b87cd790564cf8cbfe88
|
|
BLAKE2b-256 checksum How to use checksums |
5a7f6f2294b65d915ad1b47437a6916df583c106656c794453be059ea770879c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 24, 2026.
Transparency logRelease files / pypaperless-6.0.2-py3-none-any.whl
| Download URL | pypaperless-6.0.2-py3-none-any.whl |
|---|---|
| Size | 110.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0c9ce1fd67f390a8903b0310c59400a31e9f922c4ca70e54faf88d0ae93d25c8
|
|
BLAKE2b-256 checksum How to use checksums |
e1692e84802a82379fdf58cb675d75c47fd873e506c2c3c064ad4bf14d237953
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 24, 2026.
Transparency log
