Skip to content

pypaperless

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

It is built on top of httpx and Pydantic, providing type-safe, async-first access to all Paperless-ngx resources.

Installation

pip install pypaperless

Requires Python 3.12+.

Quick example

import asyncio
from pypaperless import Paperless

async def main():
    async with Paperless("localhost:8000", "your-api-token") as paperless:
        async for document in paperless.documents:
            print(document.id, document.title)

asyncio.run(main())

Features

Feature Description
Fully async Built on asyncio + httpx.AsyncClient
Type-safe models All resources are Pydantic models
All resources Documents, Correspondents, Tags, Document Types, Storage Paths, Custom Fields, Saved Views, Share Links, Workflows, Mail Accounts/Rules, Tasks, and more
CRUD operations Create, read, update and delete on all supported resources
Iteration & filtering Async iteration, pagination and server-side filtering via reduce()
Custom field system Rich, typed access to custom field values on documents
Object permissions Full support for Paperless-ngx object-level permissions
Token generation Helper to generate API tokens from username + password
Custom HTTP client Bring your own httpx.AsyncClient

Documentation