Skip to main content

Gotenberg API Client

A modern, fully-typed Python client for the Gotenberg PDF generation API, with sync and async support.

PyPI - Version PyPI - Python Version PyPI - Downloads codecov


Quick Start

pip install "gotenberg-client[httpx]"
from gotenberg_client import GotenbergClient
from pathlib import Path

with GotenbergClient("http://localhost:3000") as client:
    with client.chromium.html_to_pdf() as route:
        response = route.index(Path("my-index.html")).run()
        response.to_file(Path("my-index.pdf"))

Four lines (excluding imports) to convert HTML to PDF.

Why gotenberg-client?

Gotenberg is a powerful, Docker-based API for PDF generation and manipulation using Chromium and LibreOffice under the hood. This client gives you a clean, Pythonic interface to all of its capabilities, so you can skip the multipart form-data boilerplate and focus on your documents.

Features

  • Fully typed with concrete return types and full py.typed support
  • Sync and async APIs with identical interfaces
  • Pluggable HTTP backends -- httpx (with HTTP/2), httpx2 (with HTTP/2), niquests, or requests — install whichever you prefer
  • Pathlib-native -- pass Path objects directly, no manual file handling
  • Thoroughly tested against a real Gotenberg server across multiple Python versions
  • Broad route coverage including Chromium, LibreOffice, PDF merge/convert/split, health checks, and more
    • If there's a route you need, just ask!

Installation

An HTTP backend is required. Pick the one that suits your project:

pip install "gotenberg-client[httpx]"      # recommended — HTTP/2 and async support
pip install "gotenberg-client[httpx2]"     # alternative — HTTP/2 and async support
pip install "gotenberg-client[niquests]"   # alternative — HTTP/2 and async support
pip install "gotenberg-client[requests]"   # sync-only

If you need MIME-type detection for automatic content-type headers, add the magic extra:

pip install "gotenberg-client[httpx,magic]"

On platforms where libmagic is unavailable or unreliable (such as Windows), use the magika extra instead, which needs no native library:

pip install "gotenberg-client[httpx,magika]"

If both are installed, magic is preferred. With neither, detection falls back to the standard library's mimetypes.

Examples

HTML to PDF

from gotenberg_client import GotenbergClient
from pathlib import Path

with GotenbergClient("http://localhost:3000") as client:
    with client.chromium.html_to_pdf() as route:
        response = route.index(Path("my-index.html")).run()
        response.to_file(Path("my-index.pdf"))

Async support

from gotenberg_client import AsyncGotenbergClient
from pathlib import Path

async with AsyncGotenbergClient("http://localhost:3000") as client:
    async with client.chromium.html_to_pdf() as route:
        response = await route.index(Path("my-index.html")).run()
        response.to_file(Path("my-index.pdf"))

HTML with additional resources

from gotenberg_client import GotenbergClient
from pathlib import Path

with GotenbergClient("http://localhost:3000") as client:
    with client.chromium.html_to_pdf() as route:
        response = route.index(Path("my-index.html")).resource("image.png").resource("style.css").run()
        response.to_file(Path("my-index.pdf"))

URL to PDF in landscape

from gotenberg_client import GotenbergClient
from gotenberg_client.options import PageOrientation

with GotenbergClient("http://localhost:3000") as client:
    with client.chromium.url_to_pdf() as route:
        response = route.url("https://hello.world").orient(PageOrientation.Landscape).run()
        response.to_file(Path("my-world.pdf"))

PDF/A output format

from gotenberg_client import GotenbergClient
from gotenberg_client.options import PdfAFormat
from pathlib import Path

with GotenbergClient("http://localhost:3000") as client:
    with client.chromium.html_to_pdf() as route:
        response = (
            route.index(Path("my-index.html")).resources(["image.png", "style.css"]).pdf_format(PdfAFormat.A2b).run()
        )
        response.to_file(Path("my-index.pdf"))

PDF metadata

from gotenberg_client import GotenbergClient
from datetime import datetime

with GotenbergClient("http://localhost:3000") as client:
    with client.chromium.html_to_pdf() as route:
        response = (
            route.index("my-index.html")
            .metadata(
                title="My Document",
                author="John Doe",
                subject="Example PDF",
                keywords=["sample", "document", "test"],
                creation_date=datetime.now(),
            )
            .run()
        )
        response.to_file(Path("my-index.pdf"))

Choosing an HTTP backend

Install the backend you want, then select it explicitly (or rely on auto-detection):

from gotenberg_client import GotenbergClient

# httpx — pip install "gotenberg-client[httpx]"
with GotenbergClient("http://localhost:3000", backend="httpx") as client:
    ...

# httpx2 — pip install "gotenberg-client[httpx2]"
with GotenbergClient("http://localhost:3000", backend="httpx2") as client:
    ...

# niquests — pip install "gotenberg-client[niquests]"
with GotenbergClient("http://localhost:3000", backend="niquests") as client:
    ...

# requests (sync-only) — pip install "gotenberg-client[requests]"
with GotenbergClient("http://localhost:3000", backend="requests") as client:
    ...

# auto — tries httpx first, then niquests, then httpx2 (default)
with GotenbergClient("http://localhost:3000") as client:
    ...

Authentication

Pass a (username, password) tuple for HTTP Basic Authentication with any backend, or omit auth / pass None for the backend's default behavior:

from gotenberg_client import GotenbergClient

with GotenbergClient("http://localhost:3000", auth=("user", "secret")) as client:
    with client.chromium.html_to_pdf() as route:
        response = route.index(Path("my-index.html")).run()
        response.to_file(Path("my-index.pdf"))

You can also pass native authentication supported by your selected backend:

import httpx

with GotenbergClient(
    "https://gotenberg.example",
    backend="httpx",
    auth=httpx.DigestAuth("user", "secret"),  # Or your own httpx.Auth subclass
) as client:
    ...

HTTPX and HTTPX2 accept their own Auth instances for sync and async clients. Requests accepts requests.auth.AuthBase instances for sync clients. Niquests accepts its own AuthBase instances, plus AsyncAuthBase instances with an async client where supported by the installed Niquests version. Custom authentication should subclass the selected backend's auth base class; bare callables are not accepted.

With backend="auto", native authentication selects its backend, including for custom subclasses. Tuples and None retain the default backend preference. You can set backend= explicitly; an incompatible auth object raises TypeError during client construction. Custom HTTPX auth can access the complete multipart upload body for signing by setting requires_request_body = True. See the authentication guide for details and async usage.

How It Works

All routes follow the same pattern:

  1. Add the file(s) you want to process
  2. Configure options the route supports
  3. Call .run() and receive your result

Responses are either a SingleFileResponse or ZipFileResponse, each providing:

  • to_file(path) -- write the result to disk
  • extract_to(directory) -- extract a ZIP result into a directory (ZipFileResponse only)
  • Access to headers, status_code, and content from the underlying response

Resource cleanup

Both the client and routes should be used as context managers for proper cleanup. If that isn't possible, call .close() explicitly:

from gotenberg_client import GotenbergClient
from pathlib import Path

client = GotenbergClient("http://localhost:3000")
try:
    route = client.merge.merge()
    try:
        response = route.merge([Path("myfile.pdf"), Path("otherfile.pdf")]).run()
        response.to_file(Path("merged.pdf"))
    finally:
        route.close()
finally:
    client.close()

Documentation

For the full API reference and more examples, see the documentation.

License

gotenberg-client is distributed under the terms of the MPL 2.0 license.

Metadata

Release files for gotenberg-client 1.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for gotenberg-client 1.2.0
File Size Uploaded Provenance Actions
gotenberg_client-1.2.0.tar.gz 1.3 MB With provenance Details for gotenberg_client-1.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for gotenberg-client 1.2.0
File Interpreter ABI Platform Actions
gotenberg_client-1.2.0-py3-none-any.whl Python 3 none any Details for gotenberg_client-1.2.0-py3-none-any.whl

Total release size: 1.4 MB

Release files / gotenberg_client-1.2.0.tar.gz

Download URL gotenberg_client-1.2.0.tar.gz
Size 1.3 MB
Tags Source
SHA-256 checksum
How to use checksums
ae777fd963512a6f770647c1739d016fc80594d1fdf7b892e2319b5c81569878
BLAKE2b-256 checksum
How to use checksums
5d7b460c9de2fa87a38348651802722fc31b301e581753e04a752bbc0a4f0125
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Nov 5, 2026.

Transparency log

Release files / gotenberg_client-1.2.0-py3-none-any.whl

Download URL gotenberg_client-1.2.0-py3-none-any.whl
Size 71.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f84118e38a426ca476c82c2fe8606e933c8ab570ae610dbcb02f2e0d6c20d9b3
BLAKE2b-256 checksum
How to use checksums
04ef4753aab9e7295d747ee9f54586e70e024a94240daf759a5f399fd1f3dff7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Nov 5, 2026.

Transparency log

Security for gotenberg-client 1.2.0

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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for gotenberg_client-1.2.0.tar.gz

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 Nov 5, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page