Carbone vs Gotenberg

Carbone vs Gotenberg benchmark

Carbone published an open-source benchmark of free document converters, with the scripts, sample files and Docker commands needed to reproduce it: carboneio/document-converter-benchmark. Here are the Carbone and Gotenberg results, in requests per second (higher is better).

• HTML to PDF: with 4 threads, Carbone answers in 7.74 ms on average against 374.74 ms for Gotenberg, which is 47.0x more requests per second. With a single thread the gap is 26.2x.
• DOCX to PDF with LibreOffice on both sides: on one thread, Carbone serves 2.4x more requests per second (29.31 against 12.44). Gotenberg runs a single LibreOffice process per container (its documentation recommends adding containers to scale), while one Carbone container with 4 threads reaches 99.87 requests per second, 8.0x a Gotenberg container.
• DOCX to PDF with Carbone ICE: the converter built into Carbone, with no office suite involved, serves 96.48 requests per second on one thread (7.8x Gotenberg) and 280.52 with 4 threads.
• Carbone does slightly more work than a pure converter: it also scans every document for Carbone tags before converting it.

API equivalents: Gotenberg to Carbone

Both tools run as a local Docker container. The examples below target self-hosted instances: Gotenberg on port 3000 with multipart forms, Carbone on port 4000 with a JSON body where the file is encoded in base64.

HTML to PDF

Gotenberg expects a file named index.html. Carbone accepts any file name and uses its Chromium engine when converter is "C". Send a complete page with its <html> element: Carbone detects the file type from its content, and reads a fragment like <h1>Hello</h1> as XML.

curl --request POST http://localhost:3000/forms/chromium/convert/html \
  --form files=@index.html \
  --output result.pdf

TEMPLATE=$(base64 < index.html | tr -d '\n')
curl --request POST 'http://localhost:4000/render/template?download=true' \
  --header 'Content-Type: application/json' \
  --data '{ "template": "'"$TEMPLATE"'", "convertTo": "pdf", "converter": "C" }' \
  --output result.pdf

import { readFile, writeFile } from 'node:fs/promises';

const form = new FormData();
form.append('files', new Blob([await readFile('index.html')]), 'index.html');

const res = await fetch('http://localhost:3000/forms/chromium/convert/html', {
  method: 'POST',
  body: form
});
await writeFile('result.pdf', Buffer.from(await res.arrayBuffer()));

import { readFile, writeFile } from 'node:fs/promises';

const res = await fetch('http://localhost:4000/render/template?download=true', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    template: (await readFile('index.html')).toString('base64'),
    convertTo: 'pdf',
    converter: 'C'
  })
});
await writeFile('result.pdf', Buffer.from(await res.arrayBuffer()));

import requests

with open("index.html", "rb") as f:
    res = requests.post(
        "http://localhost:3000/forms/chromium/convert/html",
        files={"files": ("index.html", f, "text/html")},
    )
res.raise_for_status()
open("result.pdf", "wb").write(res.content)

import base64, requests

with open("index.html", "rb") as f:
    template = base64.b64encode(f.read()).decode()

res = requests.post(
    "http://localhost:4000/render/template?download=true",
    json={"template": template, "convertTo": "pdf", "converter": "C"},
)
res.raise_for_status()
open("result.pdf", "wb").write(res.content)

Word, Excel or PowerPoint to PDF

The same request works for DOCX, XLSX, PPTX, ODT, ODS, ODP and RTF. With Carbone, "converter": "L" uses LibreOffice; "O" switches to OnlyOffice and "I" to Carbone ICE, the fastest engine for DOCX and ODT.

curl --request POST http://localhost:3000/forms/libreoffice/convert \
  --form files=@document.docx \
  --output result.pdf

TEMPLATE=$(base64 < document.docx | tr -d '\n')
curl --request POST 'http://localhost:4000/render/template?download=true' \
  --header 'Content-Type: application/json' \
  --data '{ "template": "'"$TEMPLATE"'", "convertTo": "pdf", "converter": "L" }' \
  --output result.pdf

import { readFile, writeFile } from 'node:fs/promises';

const form = new FormData();
form.append('files', new Blob([await readFile('document.docx')]), 'document.docx');

const res = await fetch('http://localhost:3000/forms/libreoffice/convert', {
  method: 'POST',
  body: form
});
await writeFile('result.pdf', Buffer.from(await res.arrayBuffer()));

import { readFile, writeFile } from 'node:fs/promises';

const res = await fetch('http://localhost:4000/render/template?download=true', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    template: (await readFile('document.docx')).toString('base64'),
    convertTo: 'pdf',
    converter: 'L'
  })
});
await writeFile('result.pdf', Buffer.from(await res.arrayBuffer()));

import requests

with open("document.docx", "rb") as f:
    res = requests.post(
        "http://localhost:3000/forms/libreoffice/convert",
        files={"files": ("document.docx", f)},
    )
res.raise_for_status()
open("result.pdf", "wb").write(res.content)

import base64, requests

with open("document.docx", "rb") as f:
    template = base64.b64encode(f.read()).decode()

res = requests.post(
    "http://localhost:4000/render/template?download=true",
    json={"template": template, "convertTo": "pdf", "converter": "L"},
)
res.raise_for_status()
open("result.pdf", "wb").write(res.content)

Markdown to PDF

Gotenberg renders Markdown through an index.html wrapper that calls {{ toHTML "document.md" }}. Carbone converts the Markdown file directly, and the same call can output DOCX or HTML instead of PDF.

# index.html must contain {{ toHTML "document.md" }}
curl --request POST http://localhost:3000/forms/chromium/convert/markdown \
  --form files=@index.html \
  --form files=@document.md \
  --output result.pdf

TEMPLATE=$(base64 < document.md | tr -d '\n')
curl --request POST 'http://localhost:4000/render/template?download=true' \
  --header 'Content-Type: application/json' \
  --data '{ "template": "'"$TEMPLATE"'", "convertTo": "pdf", "converter": "L" }' \
  --output result.pdf

import { readFile, writeFile } from 'node:fs/promises';

// index.html must contain {{ toHTML "document.md" }}
const form = new FormData();
form.append('files', new Blob([await readFile('index.html')]), 'index.html');
form.append('files', new Blob([await readFile('document.md')]), 'document.md');

const res = await fetch('http://localhost:3000/forms/chromium/convert/markdown', {
  method: 'POST',
  body: form
});
await writeFile('result.pdf', Buffer.from(await res.arrayBuffer()));

import { readFile, writeFile } from 'node:fs/promises';

const res = await fetch('http://localhost:4000/render/template?download=true', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    template: (await readFile('document.md')).toString('base64'),
    convertTo: 'pdf',
    converter: 'L'
  })
});
await writeFile('result.pdf', Buffer.from(await res.arrayBuffer()));

import requests

# index.html must contain {{ toHTML "document.md" }}
with open("index.html", "rb") as html, open("document.md", "rb") as md:
    res = requests.post(
        "http://localhost:3000/forms/chromium/convert/markdown",
        files=[("files", ("index.html", html)), ("files", ("document.md", md))],
    )
res.raise_for_status()
open("result.pdf", "wb").write(res.content)

import base64, requests

with open("document.md", "rb") as f:
    template = base64.b64encode(f.read()).decode()

res = requests.post(
    "http://localhost:4000/render/template?download=true",
    json={"template": template, "convertTo": "pdf", "converter": "L"},
)
res.raise_for_status()
open("result.pdf", "wb").write(res.content)

Paper size, margins, headers and footers

Gotenberg reads page settings from form fields and separate header.html and footer.html files. Carbone reads them from custom elements placed inside the HTML itself, so the request body doesn't change.

curl --request POST http://localhost:3000/forms/chromium/convert/html \
  --form files=@index.html \
  --form files=@header.html \
  --form files=@footer.html \
  --form paperWidth=8.27 \
  --form paperHeight=11.7 \
  --form marginTop=1 \
  --form marginBottom=1 \
  --form landscape=true \
  --form printBackground=true \
  --output result.pdf

<!-- index.html, sent with the same request as above ("converter": "C") -->
<!DOCTYPE html>
<html>
<body>
  <carbone-pdf-options paper-size="A4" landscape="true"
                       margin-top="1" margin-bottom="1" />

  <carbone-pdf-header>
    <div style="font-size: 10px; width: 100%; text-align: center;">ACME Corp.</div>
  </carbone-pdf-header>

  <carbone-pdf-footer>
    <div style="font-size: 10px; width: 100%; text-align: center;">
      Page <span class="pageNumber"></span> of <span class="totalPages"></span>
    </div>
  </carbone-pdf-footer>

  <h1>Quarterly report</h1>
</body>
</html>

All the options are listed in the HTML template documentation.

Password, watermark and PDF/UA

Both tools apply PDF options in the conversion request. Gotenberg reads them from form fields, Carbone from convertTo.formatOptions.

curl --request POST http://localhost:3000/forms/libreoffice/convert \
  --form files=@document.docx \
  --form pdfua=true \
  --form userPassword=s3cr3t \
  --form watermarkSource=text \
  --form watermarkExpression=CONFIDENTIAL \
  --output protected.pdf

TEMPLATE=$(base64 < document.docx | tr -d '\n')
curl --request POST 'http://localhost:4000/render/template?download=true' \
  --header 'Content-Type: application/json' \
  --data '{
    "template": "'"$TEMPLATE"'",
    "converter": "L",
    "convertTo": {
      "formatName": "pdf",
      "formatOptions": {
        "PDFUACompliance": true,
        "EncryptFile": true,
        "DocumentOpenPassword": "s3cr3t",
        "Watermark": "CONFIDENTIAL"
      }
    }
  }' \
  --output protected.pdf

See all PDF options and watermark options.

Merge PDFs

Gotenberg has a dedicated merge route. Carbone merges PDFs while generating a document: the :appendFile formatter appends PDF files, given as URLs or base64 data URIs, at the end of the rendered template. This is an Enterprise feature, included in every Carbone Cloud plan.

curl --request POST http://localhost:3000/forms/pdfengines/merge \
  --form files=@cover.pdf \
  --form files=@annex-1.pdf \
  --form files=@annex-2.pdf \
  --output merged.pdf

# cover.html is a complete HTML page whose <body> contains:
#   <h1>{d.title}</h1>
#   {d.annexes[i].url:appendFile} {d.annexes[i+1].url}
TEMPLATE=$(base64 < cover.html | tr -d '\n')
curl --request POST 'http://localhost:4000/render/template?download=true' \
  --header 'Content-Type: application/json' \
  --data '{
    "template": "'"$TEMPLATE"'",
    "converter": "C",
    "convertTo": "pdf",
    "data": {
      "title": "Contract 2026-042",
      "annexes": [
        { "url": "https://example.com/annex-1.pdf" },
        { "url": "https://example.com/annex-2.pdf" }
      ]
    }
  }' \
  --output merged.pdf

To merge many documents generated from the same template, use batch generation with "batchOutput": "pdf". It is included in Carbone Cloud. When self-hosted, it requires the Enterprise Edition and CARBONE_NB_REPORT_MAX_PER_BATCH set to the maximum number of documents per batch.

Asynchronous conversion with a webhook

Both tools can answer immediately and call your server when the file is ready. Gotenberg replies 204 No Content, then posts the PDF to your webhook. Carbone posts a JSON object with a renderId, and you download the file with GET /render/{renderId}. Webhooks are available in every edition, including the free Community Edition. When self-hosted, Carbone refuses webhook URLs on a local network by default (see CARBONE_SECURITY_LEVEL).

curl --request POST http://localhost:3000/forms/libreoffice/convert \
  --header 'Gotenberg-Webhook-Url: https://my-app.com/webhook' \
  --header 'Gotenberg-Webhook-Events-Url: https://my-app.com/webhook/events' \
  --form files=@document.docx

TEMPLATE=$(base64 < document.docx | tr -d '\n')
curl --request POST 'http://localhost:4000/render/template' \
  --header 'Content-Type: application/json' \
  --header 'carbone-webhook-url: https://my-app.com/webhook' \
  --header 'carbone-webhook-header-authorization: my-secret' \
  --data '{ "template": "'"$TEMPLATE"'", "convertTo": "pdf" }'

URL to PDF

Gotenberg can open a URL in Chromium and print it. Carbone doesn't fetch web pages: download the HTML first, then convert it like any HTML file.

curl --request POST http://localhost:3000/forms/chromium/convert/url \
  --form url=https://example.com/invoice/42 \
  --output result.pdf

curl --silent https://example.com/invoice/42 --output page.html
TEMPLATE=$(base64 < page.html | tr -d '\n')
curl --request POST 'http://localhost:4000/render/template?download=true' \
  --header 'Content-Type: application/json' \
  --data '{ "template": "'"$TEMPLATE"'", "convertTo": "pdf", "converter": "C" }' \
  --output result.pdf

Beyond conversion: fill a template with JSON data

This is where Carbone and Gotenberg differ most. With Gotenberg, you render the HTML with your own template engine before converting it. Carbone does both in one call: add {d.field} tags to an HTML, DOCX, XLSX, PPTX or Markdown file, and send your JSON in data.

# invoice.html: <html><body><h1>Invoice {d.id}</h1> <p>Customer: {d.customer.name}</p></body></html>
TEMPLATE=$(base64 < invoice.html | tr -d '\n')
curl --request POST 'http://localhost:4000/render/template?download=true' \
  --header 'Content-Type: application/json' \
  --data '{
    "template": "'"$TEMPLATE"'",
    "converter": "C",
    "convertTo": "pdf",
    "data": { "id": "2026-042", "customer": { "name": "ACME Corp." } }
  }' \
  --output invoice.pdf

Loops, conditions, number and date formatters, translations, charts and barcodes are described in the template design documentation.

Frequently asked questions

Still have a question? Chat with us.