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 |
[!TIP] 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 and Claude. Feedback and contributions are always welcome.
Check out all contributors.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file pypaperless-6.0.1.tar.gz.
File metadata
- Download URL: pypaperless-6.0.1.tar.gz
- Upload date:
- Size: 275.2 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
31d0f7c949ced56891b275a1769489fd69f69fc3fc69ef3d8390c1924df52e7d
|
|
| MD5 |
9cb4786f51aa7f3f8620fee8764139d6
|
|
| BLAKE2b-256 |
a752f18abfa04ce6f26dbab9997932b0250f6e52a20954d6d8507b1a70f2fb68
|
Provenance
The following attestation bundles were made for pypaperless-6.0.1.tar.gz:
Publisher:
release.yml on tb1337/pypaperless
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
pypaperless-6.0.1.tar.gz -
Subject digest:
31d0f7c949ced56891b275a1769489fd69f69fc3fc69ef3d8390c1924df52e7d - Sigstore transparency entry: 2507026754
- Sigstore integration time:
-
Permalink:
tb1337/pypaperless@5d67d60514dd63cf7b4d6ba29928df4babea70f4 -
Branch / Tag:
refs/tags/v6.0.1 - Owner: https://github.com/tb1337
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@5d67d60514dd63cf7b4d6ba29928df4babea70f4 -
Trigger Event:
release
-
Statement type:
File details
Details for the file pypaperless-6.0.1-py3-none-any.whl.
File metadata
- Download URL: pypaperless-6.0.1-py3-none-any.whl
- Upload date:
- Size: 109.4 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
6cb9896a209a78ada7e983456184d94edba27007bf36bce43f87a3efd95f3c9f
|
|
| MD5 |
6f378e29c8cf3d29618cd01808efb278
|
|
| BLAKE2b-256 |
0d754556229d5660a43ef2a90415bf8c5f2bcbc3bef0e3be12fc580be3407d19
|
Provenance
The following attestation bundles were made for pypaperless-6.0.1-py3-none-any.whl:
Publisher:
release.yml on tb1337/pypaperless
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
pypaperless-6.0.1-py3-none-any.whl -
Subject digest:
6cb9896a209a78ada7e983456184d94edba27007bf36bce43f87a3efd95f3c9f - Sigstore transparency entry: 2507027771
- Sigstore integration time:
-
Permalink:
tb1337/pypaperless@5d67d60514dd63cf7b4d6ba29928df4babea70f4 -
Branch / Tag:
refs/tags/v6.0.1 - Owner: https://github.com/tb1337
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@5d67d60514dd63cf7b4d6ba29928df4babea70f4 -
Trigger Event:
release
-
Statement type:
