---
id: gotenberg-client
version: "1.0.0"
license: MPL-2.0
license_treatment: copyleft
maintenance: active
---

# gotenberg-client — A Python client for interfacing with the Gotenberg API

License: copyleft · Maintenance: active · Downloads: 153.0K/mo

## What it is and what it does

gotenberg-client is a Python wrapper around the Gotenberg PDF generation and manipulation API. It abstracts away the HTTP boilerplate and multipart form-data handling, giving you a clean, type-safe interface to convert HTML files and URLs to PDF, merge or split PDFs, and apply formatting options like page orientation and PDF/A output formats. The client supports both synchronous and asynchronous workflows and lets you choose your HTTP backend (httpx with HTTP/2 support, niquests, or requests).

You install an HTTP backend extra alongside the package, then instantiate a client pointing to your Gotenberg server URL. Routes follow a fluent builder pattern: add files, configure options, call `.run()`, and write the result to disk or extract it. The package is fully typed with py.typed support, tested against a real Gotenberg server, and actively maintained. It requires Python 3.10 or later and a running Gotenberg instance to function.

Use it for:

- Convert HTML files with embedded CSS and images to PDF in a web application backend.
- Render web pages (URLs) to PDF on demand for reports or document generation.
- Merge multiple PDF files into a single document programmatically.
- Generate PDF/A-compliant archival documents with embedded metadata.
- Build async PDF pipelines in high-concurrency applications using the AsyncGotenbergClient.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

A fully-typed Python client for the Gotenberg PDF generation API, supporting sync and async operations to convert HTML, URLs, and other documents to PDF via a remote Gotenberg server.

Yes. The package is actively maintained, has no known vulnerabilities, low install friction, and provides a clean, well-typed interface to a powerful PDF service. Install it if you have a Gotenberg server running and need a Pythonic client to interact with it. The MPL-2.0 license is permissive for most use cases; review it if you plan to redistribute modified versions.

## Install

pip install gotenberg-client
uv add gotenberg-client
poetry add gotenberg-client

## Installing gotenberg-client

Before you install: Low friction: pure Python wheel with a single runtime dependency (typing-extensions). Actively maintained with a release 7 days ago. Supports modern Python versions (3.10–3.14) and both CPython and PyPy.

License in practice: Distributed under MPL-2.0 (copyleft). You may use and modify the package freely, but derivative works must retain the same license and disclose source changes.

Quickstart:

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"))

Requires a running Gotenberg server (typically Docker-based) accessible at the configured URL.

Verify before relying:

- Whether the package handles all Gotenberg API routes or if gaps remain (description mentions 'ask if you need a route').
- Performance characteristics and memory usage when processing large documents or concurrent requests.

## Package facts

- License: MPL-2.0 (copyleft)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 153.0K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

gotenberg python client, html to pdf conversion, pdf generation api, async pdf client, document to pdf service, chromium pdf rendering, gotenberg api wrapper, pdf-generation, document-conversion, async-support

[View on SkillFed](https://skillfed.io/packages/gotenberg-client) · [View on PyPI](https://pypi.org/project/gotenberg-client/)