pypaperless 6.0.0rc2

Little api client for paperless(-ngx).

pypaperless

pypaperless is a modern, fully async Python client library for the Paperless-ngx REST API.

• Features
• Quick example
• Installation
• Documentation
• Compatibility matrix
• Authors & contributors

---

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.