Convert to PDF
Converts documents to PDF using LibreOffice. Accepts Microsoft Office (Word, Excel, PowerPoint), OpenDocument, plain text, and many other formats. You can upload one or more files per request.
Sections marked (LibreOffice) apply during conversion. Sections marked (PDF Engines) post-process the resulting PDF with external tools such as QPDF, pdfcpu, and PDFtk; see PDF Engines.
See the LibreOffice module configuration for startup and behavior flags.
Basics
curl \
--request POST http://localhost:3000/forms/libreoffice/convert \
--form files=@/path/to/docx \
-o my.pdf
- 200
- 400
- 503
Content-Disposition: attachment; filename={output-filename.ext}
Content-Type: {content-type}
Content-Length: {content-length}
Gotenberg-Trace: {trace}
Body: {output-file}
Content-Type: text/plain; charset=UTF-8
Gotenberg-Trace: {trace}
Body: {error}
Content-Type: text/plain; charset=UTF-8
Gotenberg-Trace: {trace}
Body: {error}
Rendering Behavior
Layout & Pages
falsefalsefalsefalsecurl \
--request POST http://localhost:3000/forms/libreoffice/convert \
--form files=@/path/to/document.docx \
--form landscape=true \
-o my.pdf
Supported Extensions
| Family | Supported Extensions |
|---|---|
| Word Processing | .doc, .docx, .docm, .dot, .dotm, .dotx, .odt, .fodt, .ott, .rtf, .txt, .wps, .wpd, .pages, .abw, .zabw, .lwp, .mw, .mcw, .hwp, .sxw, .stw, .sgl, .vor, .602, .bib, .xml, .cwk, .psw, .uof |
| Spreadsheets | .xls, .xlsx, .xlsm, .xlsb, .xlt, .xltm, .xltx, .xlw, .ods, .fods, .ots, .csv, .numbers, .123, .wk1, .wks, .wb2, .dbf, .dif, .slk, .sxc, .stc, .uos, .pxl, .sdc |
| Presentations | .ppt, .pptx, .pptm, .pot, .potm, .potx, .pps, .odp, .fodp, .otp, .key, .sxi, .sti, .uop, .sdd, .sdp, .fopd |
| Graphics & Drawing | .odg, .fodg, .otg, .vsd, .vsdx, .vsdm, .vdx, .cdr, .svg, .svm, .wmf, .emf, .cgm, .dxf, .std, .sxd, .pub, .wpg, .sda, .odd, .met, .cmx, .eps |
| Images | .jpg, .jpeg, .png, .bmp, .gif, .tif, .tiff, .pbm, .pgm, .ppm, .xbm, .xpm, .pcx, .pcd, .pct, .psd, .tga, .ras, .pwp |
| Web & Other | .html, .htm, .xhtml, .epub, .pdf, .pdb, .ltx, .mml, .smf, .sxm, .sxg, .oth, .odm, .swf |
LibreOffice is not a 1:1 clone of Microsoft Office. Documents with complex styling, Smart Art, or highly specific formatting may render slightly differently.
Fonts & Layout Fidelity
LibreOffice relies on installed fonts to calculate page breaks and layout. Missing fonts are the most common cause of layout issues and shifted pagination.
Install all required fonts in your Docker image (via a custom Dockerfile). See Fonts configuration.
Image Compression
- Lossless (PNG): Best for line art, diagrams, or images with flat colors. Enable with
losslessImageCompression. - Lossy (JPEG): The default. Best for photographs or complex gradients. Significantly smaller file size.
false90maxImageResolution.false300curl \
--request POST http://localhost:3000/forms/libreoffice/convert \
--form files=@/path/to/document.docx \
--form losslessImageCompression=false \
--form quality=50 \
--form reduceImageResolution=true \
--form maxImageResolution=75 \
-o my.pdf
Notes & Slides
falsefalseexportNotesPages is true, exports only the notes pages.falsefalsefalseLinks
falsefalseMacros
Macros in documents (e.g., .docm, .xlsm, .pptm) are disabled by default during conversion. Files are still converted, but macro-generated content will not execute.
Linked Content
Documents can reference content by link instead of storing it: OOXML images marked TargetMode="External", RTF INCLUDEPICTURE, ODT linked images.
Since 8.34.0, LibreOffice drops linked content: an uploaded document always loads from an untrusted location, so linked file:// paths and external URLs are not resolved. The conversion still returns 200 OK with the linked content absent. There is no opt-out; embedded content is unaffected, so embed images instead of linking them.
Since 8.32.0, any outbound fetch LibreOffice still performs routes through the same pinning proxy used by Chromium. Allow/deny lists and IP-class checks apply. The proxy rejects forbidden destinations inside the conversion, which succeeds without the resource.
Structure & Metadata
Document Outline (LibreOffice)
Configure how LibreOffice generates PDF bookmarks (the sidebar) and internal indexes like the Table of Contents. Your source document must use proper heading styles (e.g., Heading 1, Heading 2) or explicit bookmarks to generate the hierarchy.
truetruefalsefalsecurl \
--request POST http://localhost:3000/forms/libreoffice/convert \
--form files=@/path/to/document.docx \
--form exportBookmarks=false \
--form exportBookmarksToPdfDestination=true \
--form updateIndexes=false \
-o my.pdf
Native Flattening (LibreOffice)
Set exportFormFields to false to prevent LibreOffice from creating interactive PDF widgets, effectively flattening them during conversion. Faster than post-processing.
This also fixes clipping when form fields reference fonts that aren't embedded: LibreOffice sizes the widget boxes with a fallback font, so they come out too small. Flattening removes the widgets and the mismatch.
truefalsecurl \
--request POST http://localhost:3000/forms/libreoffice/convert \
--form files=@/path/to/document.docx \
--form exportFormFields=false \
-o my.pdf
Metadata (PDF Engines)
Inject XMP metadata (Author, Title, Copyright, Keywords, etc.) into the PDF as a JSON object.
Not all tags are writable. Gotenberg uses ExifTool under the hood. See the XMP Tag Name documentation for valid keys. Writing metadata usually breaks PDF/A compliance.
Nonecurl \
--request POST http://localhost:3000/forms/libreoffice/convert \
--form files=@/path/to/document.docx \
--form 'metadata={"Author":"Julien Neuhart","Copyright":"Julien Neuhart","CreationDate":"2006-09-18T16:27:50-04:00","Creator":"Gotenberg","Keywords":["first","second"],"Marked":true,"ModDate":"2006-09-18T16:27:50-04:00","PDFVersion":1.7,"Producer":"Gotenberg","Subject":"Sample","Title":"Sample","Trapped":"Unknown"}' \
-o my.pdf
Attachments (PDF Engines)
Attach external files directly inside the PDF container. Commonly used for e-invoicing standards like ZUGFeRD / Factur-X, which require a machine-readable XML invoice as an attachment.
Provide per-attachment metadata with embedsMetadata to satisfy PDF/A-3 and Factur-X requirements: each entry sets the embedded file stream's /Subtype, writes /AFRelationship on the file specification, and references the attachment from the Document Catalog's /AF array.
NoneNonecurl \
--request POST http://localhost:3000/forms/libreoffice/convert \
--form files=@/path/to/document.docx \
--form embeds=@factur-x.xml \
--form embeds=@logo.png \
--form embedsMetadata='{"factur-x.xml":{"mimeType":"text/xml","relationship":"Alternative"},"logo.png":{"mimeType":"image/png","relationship":"Supplement"}}' \
-o my.pdf
Factur-X (PDF Engines)
Produces a Factur-X / ZUGFeRD e-invoice in one request: upload the CII invoice XML with facturxXml and set facturxConformanceLevel. Both fields are required together. Gotenberg embeds the XML into the resulting PDF and never converts or merges it like other uploaded files. Requires a PDF engine that supports the feature (QPDF by default). See PDF Engines module configuration.
See the dedicated Factur-X route for the full behavior: canonical embedding, XMP metadata, and the PDF/A-3 requirement.
NoneINVOICE1.0Nonecurl \
--request POST http://localhost:3000/forms/libreoffice/convert \
--form files=@/path/to/invoice.docx \
--form facturxXml=@/path/to/factur-x.xml \
--form 'facturxConformanceLevel=EN 16931' \
-o my.pdf
Flatten (PDF Engines)
Merges all interactive form fields (text inputs, checkboxes, etc.) into the page content, making the PDF non-editable.
falsecurl \
--request POST http://localhost:3000/forms/libreoffice/convert \
--form files=@/path/to/document.docx \
--form flatten=true \
-o my.pdf
Merge (PDF Engines)
Converts each file to PDF individually, then merges them in alphanumeric order (numbers first, then alphabetical).
curl \
--request POST http://localhost:3000/forms/libreoffice/convert \
--form files=@/path/to/1_document.docx \
--form files=@/path/to/2_document.docx \
--form merge=true \
-o my.pdf
Split & Page Ranges
Native Printing (LibreOffice)
Happens during the conversion. Applied independently to each uploaded file.
All pagescurl \
--request POST http://localhost:3000/forms/libreoffice/convert \
--form files=@/path/to/document.docx \
--form nativePageRanges=1-5 \
-o my.pdf
Post-Processing (PDF Engines)
Splits pages after the PDF has been generated using a PDF engine (pdfcpu, QPDF, or PDFtk). Applied to each file individually, or to the combined output after the merge operation.
When splitMode is set to pages, Gotenberg does not validate the splitSpan syntax. The value is passed directly to the underlying PDF engine, and the valid syntax depends on which engine you have configured:
| Engine | Syntax Reference |
|---|---|
| pdfcpu (Default) | See pdfcpu /trim documentation |
| QPDF | See QPDF page-ranges documentation |
| PDFtk | See PDFtk cat operation |
Check the PDF Engines module configuration to see which engine is active.
NoneNonefalsecurl \
--request POST http://localhost:3000/forms/libreoffice/convert \
--form files=@/path/to/document.docx \
--form splitMode=intervals \
--form splitSpan=1 \
-o my.zip
Watermark & Stamp
Native Watermarks (LibreOffice)
Text-only watermarks applied during conversion. For image or PDF watermarks, use the PDF Engines watermark below.
None838822300HelveticaNonecurl \
--request POST http://localhost:3000/forms/libreoffice/convert \
--form files=@/path/to/document.docx \
--form nativeWatermarkText=CONFIDENTIAL \
--form nativeWatermarkFontHeight=48 \
--form nativeWatermarkRotateAngle=450 \
-o my.pdf
Watermark (PDF Engines)
image and pdf sources require an uploaded watermark file. watermarkExpression cannot reference an arbitrary filesystem path; the route returns 400 Bad Request.
NoneNoneNoneNoneNonecurl \
--request POST http://localhost:3000/forms/libreoffice/convert \
--form files=@/path/to/document.docx \
--form watermarkSource=text \
--form watermarkExpression=CONFIDENTIAL \
--form 'watermarkOptions={"opacity":0.25,"rotation":45}' \
-o my.pdf
Stamp (PDF Engines)
image and pdf sources require an uploaded stamp file. stampExpression cannot reference an arbitrary filesystem path; the route returns 400 Bad Request.
NoneNoneNoneNoneNonecurl \
--request POST http://localhost:3000/forms/libreoffice/convert \
--form files=@/path/to/document.docx \
--form stampSource=text \
--form stampExpression=APPROVED \
--form 'stampOptions={"opacity":0.5,"rotation":0}' \
-o my.pdf
Rotate (PDF Engines)
Rotates pages by 90, 180, or 270 degrees during post-processing.
curl \
--request POST http://localhost:3000/forms/libreoffice/convert \
--form files=@/path/to/document.docx \
--form rotateAngle=90 \
-o my.pdf
PDF/A & PDF/UA
Use the pdfa and pdfua form fields to convert the PDF into a standardized format.
- PDF/A: Specialized for the digital preservation of electronic documents (Archival).
- PDF/UA: Specialized for Universal Accessibility, ensuring documents are accessible to assistive technologies.
Nonefalsecurl \
--request POST http://localhost:3000/forms/libreoffice/convert \
--form files=@/path/to/document.docx \
--form pdfa=PDF/A-1b \
--form pdfua=true \
-o my.pdf
Encryption
Open Document (LibreOffice)
The password form field opens a password-protected source file.
Nonecurl \
--request POST http://localhost:3000/forms/libreoffice/convert \
--form files=@/path/to/document.docx \
--form password=foo \
-o my.pdf
Post-Processing (PDF Engines)
Set passwords and permissions to control PDF access. The user password is required to open the PDF. The owner password grants full access and lifts the permission restrictions; when empty, it defaults to the user password.
Since 8.34.0, an owner password alone produces an owner-only PDF: it opens without a password, but the document permissions apply. Permission restrictions require a userPassword or an ownerPassword, otherwise Gotenberg returns 400 Bad Request. Restrictions are advisory: viewers honor them, but they are not cryptographically enforced once the document opens.
Encryption strength (e.g., AES-256) and permission handling depend on the active PDF engine: QPDF honors each permission individually, pdfcpu restricts all permissions if any one is denied, and PDFtk supports neither owner-only encryption nor permission restrictions. See PDF Engines module configuration.
NoneNonetruetruetruetruetruetruecurl \
--request POST http://localhost:3000/forms/libreoffice/convert \
--form files=@/path/to/document.docx \
--form userPassword=my_user_password \
--form ownerPassword=my_owner_password \
--form allowCopying=false \
-o my.pdf
PDF Viewer Preferences
Control how PDF viewers display the document on open. These preferences are embedded during conversion and take effect when a reader (Adobe Acrobat, browser PDF viewer, etc.) opens the file.
0101000falsefalsefalsefalsetruefalsefalsefalsetrue-1curl \
--request POST http://localhost:3000/forms/libreoffice/convert \
--form files=@/path/to/document.docx \
--form initialView=1 \
--form magnification=2 \
--form displayPDFDocumentTitle=true \
--form hideViewerToolbar=true \
-o my.pdf
What's Next?
Combine or transform the result in Manipulate PDFs, or deliver it asynchronously with webhooks.