Convert to PDF
Converts uploaded documents to PDF using LibreOffice.
This endpoint processes files provided directly in the multipart/form-data request body.
It accepts a wide range of formats, including Microsoft Office (Word, Excel, PowerPoint), OpenOffice, and plain text files.
You can upload one or more documents, and the API will convert all supported files found in the request.
You can configure the LibreOffice module behavior. See the LibreOffice module configuration for details.
Basics
curl \
--request POST http://localhost:3000/forms/libreoffice/convert \
--form files=@/path/to/docx \
-o my.pdf
- 200 OK
- 400 Bad Request
- 503 Service Unavailable
Content-Disposition: attachment; filename={output-filename.pdf}
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: Service Unavailable
Rendering Behavior
falsefalse90maxImageResolution.false300falsefalsefalseexportNotesPages is set to true, if only notes pages are exported to PDF.falsefalsefalsefalsefalsefalsefalsecurl \
--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
Supported Extensions
The LibreOffice route supports converting a vast array of document formats into PDF. From modern office standards and open-source formats to legacy files and vector graphics, below is the comprehensive list of supported file extensions grouped by document family.
| 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 |
While LibreOffice provides excellent support for Microsoft Office formats (e.g., .docx, .xlsx, .pptx), it is not a 1:1 clone.
Documents containing complex styling, proprietary Smart Art, or highly specific formatting features may render slightly differently than they do in Microsoft Word or Excel.
Fonts & Layout Fidelity
Fonts are critical. LibreOffice relies on installed fonts to calculate page breaks and layout. If a specific font used in your document is missing from the Gotenberg container, LibreOffice will substitute it with a default one. This is the most common cause of layout issues and shifted pagination.
For the best results, ensure all required fonts are installed in your Docker image (e.g., via a custom Dockerfile).
See the Fonts configuration for more details.
Image Compression
How LibreOffice compresses images inside your PDF impacts both visual quality and the final file size:
- Lossless (PNG): Best for documents containing line art, diagrams, or images with text and flat colors. It prevents visual artifacts and ensures sharp edges. Enable the
losslessImageCompressionform field to use this method. - Lossy (JPEG): The default behavior. Best for documents containing high-resolution photographs or complex gradients, as it significantly reduces the PDF's file size.
Macros
For security reasons, macros contained in documents (e.g., .docm, .xlsm, .pptm) are disabled by default during the conversion process.
The files will still be converted, but any dynamic content or scripts generated by macros will not be executed.
Structure & Metadata
truetruefalsefalsetruefalseNonefalseNoneDocument Outline & Navigation (LibreOffice)
Configure how LibreOffice generates PDF bookmarks (the sidebar) and internal indexes like the Table of Contents.
- Process: Happens during the document-to-PDF conversion.
- Requirement: Your source document must use proper heading styles (e.g., Heading 1, Heading 2) or explicit bookmarks to generate the hierarchy.
curl \
--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
Metadata (PDF Engines)
Use the metadata form field to inject XMP metadata into the generated PDF. This allows you to set properties like
Author, Title, Copyright, and Keywords by passing a JSON-formatted object.
Not all metadata tags are writable. Gotenberg relies on ExifTool for this operation. See the XMP Tag Name documentation for a list of potential keys.
Writing metadata involves modifying the PDF structure and usually breaks PDF/A compliance.
curl \
--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)
Use the embeds form field to attach external files directly inside the PDF container.
Common Use Case: This is essential for e-invoicing standards like ZUGFeRD / Factur-X, which require a human-readable PDF to carry a machine-readable XML invoice as an attachment.
curl \
--request POST http://localhost:3000/forms/libreoffice/convert \
--form files=@/path/to/document.docx \
--form embeds=@invoice.xml \
--form embeds=@logo.png \
-o my.pdf
Native Flattening (LibreOffice)
Use the exportFormFields form field to prevent LibreOffice from creating interactive PDF widgets, effectively "flattening" the form fields directly into the document's visual layout as static text and shapes.
- Process: Happens during the document-to-PDF conversion.
- Performance: Faster and more efficient than post-processing, as the interactive PDF layers are never generated in the first place.
curl \
--request POST http://localhost:3000/forms/libreoffice/convert \
--form files=@/path/to/document.docx \
--form exportFormFields=false \
-o my.pdf
Flatten (PDF Engines)
Use the flatten form field to make the PDF non-interactive after it has been generated.
- Process: Gotenberg generates the full PDF, then uses a PDF Engine to merge all interactive form fields (text inputs, checkboxes, etc.) directly into the page content.
- Output: A flattened PDF that cannot be modified by the end-user.
- Use Case: Ideal if you are combining flattening with other post-processing operations (like merging or metadata extraction) handled by the PDF engines.
curl \
--request POST http://localhost:3000/forms/libreoffice/convert \
--form files=@/path/to/document.docx \
--form flatten=true \
-o my.pdf
Merge (PDF Engines)
Use the merge form field to combine multiple converted documents into a single PDF file.
Gotenberg first converts each submitted file to PDF individually using LibreOffice. Once the conversions are complete, a PDF engine merges the resulting files together. The documents are appended in alphanumeric order based on their original filenames (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
All pagesNoneNonefalseNative Printing (LibreOffice)
Use the nativePageRanges form field to tell LibreOffice which pages to print.
- Process: Happens during the conversion.
- Performance: High.
- Behavior: Applied independently to each uploaded file.
curl \
--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)
Use the splitMode form fields to extract pages after the PDF has been generated.
- Process: Gotenberg generates the PDF, then splits it using a PDF Engine (pdfcpu, QPDF, or PDFtk).
- Performance: Slower (requires a second pass).
- Behavior: Applied to each uploaded 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 Configuration to see which engine is active.
curl \
--request POST http://localhost:3000/forms/libreoffice/convert \
--form files=@/path/to/document.docx \
--form splitMode=intervals \
--form splitSpan=1 \
-o my.zip
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
NoneNoneNoneOpen Document (LibreOffice)
Use the password form field if the source file is password-protected.
curl \
--request POST http://localhost:3000/forms/libreoffice/convert \
--form files=@/path/to/document.docx \
--form password=foo \
-o my.pdf
Post-Processing (PDF Engines)
Secure your PDF by setting passwords that control access and permissions.
- User Password: Required to open and view the PDF.
- Owner Password: Required to modify permissions (e.g., printing, copying text, extracting pages).
The encryption strength (e.g., AES-256) depends on the configured PDF Engine (QPDF, pdfcpu, or PDFtk).
Check the PDF Engines Configuration to see which engine is active.
curl \
--request POST http://localhost:3000/forms/libreoffice/convert \
--form files=@/path/to/document.docx \
--form userPassword=my_user_password \
--form ownerPassword=my_owner_password \
-o my.pdf
