Skip to content

Getting started

This page walks you through the first steps with pypaperless: installation, creating a session and obtaining an API token.

Installation

Install from PyPI:

pip install pypaperless

Requires Python 3.12 or higher.

Your first session

Import the Paperless class and create an instance with your Paperless-ngx host and API token.

pypaperless is fully async. All API calls must be made inside an async function.

The cleanest way to use pypaperless is as an async context manager. It calls initialize() and close() automatically.

import asyncio
from pypaperless import Paperless

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

asyncio.run(main())

Manual lifecycle

You can also manage the lifecycle manually by calling initialize() and close() yourself:

async def main():
    paperless = Paperless("localhost:8000", "your-api-token")
    await paperless.initialize()

    # do something...

    await paperless.close()

URL formats

The url parameter accepts a variety of formats. pypaperless normalises the URL automatically.

Input Resolved to
"localhost:8000" https://localhost:8000
"http://192.168.1.10:8000" http://192.168.1.10:8000
"https://paperless.example.com" https://paperless.example.com

Note

When no scheme is provided, https:// is assumed.

Generating an API token

If you don't have a token yet, you can generate one from a username and password using the static helper method:

token = await Paperless.generate_api_token(
    "localhost:8000",
    username="admin",
    password="secret",
)

paperless = Paperless("localhost:8000", token)

Warning

generate_api_token sends credentials as plain JSON. Do not use this in production environments or automated pipelines where security matters.

Checking connection status

After initialize(), you can inspect the host:

async with Paperless("localhost:8000", "your-api-token") as paperless:
    print(paperless.is_initialized)   # True
    print(paperless.host_version)     # e.g. "2.15.0"
    print(paperless.host_api_version) # e.g. 9

Next steps