Skip to content
Get packs

Guide · Open source

How to use Gotenberg: run the Docker API and convert files to PDF

Updated · written with AI from the project's own documentation and checked against our catalogue data

Gotenberg is a Docker-based API that converts documents to PDF. You send it a file or a web address over HTTP, and it returns a PDF, using headless Chromium and LibreOffice behind the scenes. This guide shows how to start it, make a first conversion with curl, and decide whether it fits your application.

Gotenberggotenberg/gotenberg · ★ 13.5k · MIT

Quick start

  1. 1Install Docker. Gotenberg's only listed prerequisite is Docker. Make sure Docker is installed and running on your machine or server.
  2. 2Start the Gotenberg container. Run docker run --rm -p 3000:3000 gotenberg/gotenberg:8 to start the API on port 3000.
  3. 3Send a test conversion. Use curl to POST a URL to /forms/chromium/convert/url and save the response with -o.
  4. 4Open the resulting PDF. Check the saved file to confirm the page rendered as expected.
  5. 5Call the API from your application. Send multipart/form-data requests from your code to the same endpoints, using the parameters in the full documentation.
  6. 6Read the documentation for other formats. Look up the routes for Office files, HTML, Markdown and PDF operations at gotenberg.dev before building on them.

What Gotenberg does and who it is for

Gotenberg is a server you run yourself. Your application sends files or URLs with multipart/form-data, and Gotenberg returns a PDF. The README says you do not need to manage Chromium, LibreOffice, or fonts yourself.

It suits developers turning HTML or web pages into PDFs from their own software, teams generating Office documents that must be delivered as PDFs, and backend services that want PDF conversion without installing these tools on the host.

  • HTML, URL and Markdown to PDF via Headless Chromium
  • Office documents to PDF via LibreOffice (100+ formats, per the README)
  • Merge, split, rotate and flatten PDFs
  • Watermark, stamp and encrypt PDFs
  • PDF/A and PDF/UA compliance, screenshots, and reading or writing metadata and bookmarks

Install Gotenberg with Docker

The only prerequisite listed in the README is Docker. Start the service with the command below. It maps port 3000 on your machine to port 3000 in the container, and the --rm flag removes the container when it stops.

The README's full documentation covers installation options beyond this quick start, so check it if you need something other than this command.

docker run --rm -p 3000:3000 gotenberg/gotenberg:8

Convert a web page to PDF with curl

With the container running, send a POST request to the Chromium URL conversion route. The url form field holds the address to convert. The -o flag saves the response as invoice.pdf.

The README's example converts a sample invoice template page. Replace the url value with the page you need.

curl \ --request POST http://localhost:3000/forms/chromium/convert/url \ --form url=https://sparksuite.github.io/simple-html-invoice-template/ \ -o invoice.pdf

Convert other document types

The README says Office documents are converted to PDF via LibreOffice and lists 100+ formats. It also says HTML and Markdown are handled through Headless Chromium. The README excerpt does not show the exact routes or form fields for these, so consult the full documentation at gotenberg.dev before writing production code.

Check that the output matches your needs, especially for complex layouts or fonts.

  • Use the URL route for live web pages
  • Use the documentation for HTML, Markdown and Office file routes

Use PDF post-processing features

The README lists operations that work on PDFs: merging, splitting, rotating, flattening, watermarking, stamping, encrypting, PDF/A and PDF/UA compliance, and reading or writing metadata and bookmarks. Look up the exact endpoints in the full documentation, since the README excerpt does not list them.

Know the limits before you commit

Gotenberg is a self-hosted API, so you run it, update it and keep it available. The README excerpt is truncated, so confirm any specific capability in the official docs before relying on it.

  • Requires Docker on the host
  • You maintain the service yourself
  • No graphical interface; it is used through HTTP requests

What people use it for

  • Turning a web page or HTML invoice into a PDF from a backend service
  • Converting Office documents to PDF so they can be delivered through an API
  • Running PDF conversion inside your own infrastructure instead of on the host
  • Adding PDF post-processing such as merging or watermarking to a document pipeline

Frequently asked questions

Is Gotenberg free to use?

Gotenberg is released under the MIT licence, according to the project's listing. You run it yourself with Docker, so you are responsible for hosting and maintaining it.

What do I need to install Gotenberg?

The README lists Docker as the prerequisite. You start the service with docker run --rm -p 3000:3000 gotenberg/gotenberg:8 and then send requests to it over HTTP.

Do I need to install Chromium or LibreOffice?

No. The README says Gotenberg handles conversion with headless Chromium and LibreOffice, so you do not need to install them on the host.

How do I convert a URL to PDF with Gotenberg?

Send a POST request to http://localhost:3000/forms/chromium/convert/url with a url form field, as shown in the curl example. The response is the PDF.

Is Gotenberg a desktop app?

No. The README describes it as an API served via Docker. Users who want a graphical desktop tool should look elsewhere.

How does Gotenberg compare to wkhtmltopdf or Puppeteer?

The project lists wkhtmltopdf, Puppeteer, Carbone and pdfme as comparable projects. Gotenberg is a Docker-based HTTP service, while those are libraries or tools that you call directly. Compare them against your own needs, such as the formats you must convert.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Gotenberg suits developers and backend teams who want a self-hosted HTTP API for turning HTML, URLs and Office files into PDFs without installing Chromium or LibreOffice. It is a poor fit if you only convert files occasionally, want a desktop app, or do not want to run and maintain a Docker service.

Install options & downloads