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.

See the LibreOffice module configuration for startup and behavior flags.

Basics

POST/forms/libreoffice/convert

Headers

Gotenberg-Output-Filenamestring

The filename of the resulting file - Gotenberg automatically appends the file extension. Defaults to a random UUID filename.

Gotenberg-Tracestring

A custom request ID to identify the request in the logs; overrides the default UUID.

Form Files

filesfile[]required

At least one file to convert to PDF.

Example Request

cURL

curl \
--request POST http://localhost:3000/forms/libreoffice/convert \
--form files=@/path/to/docx \
-o my.pdf

Responses

200

The PDF file has been successfully created. Returns a ZIP archives if many files have been uploaded.

Content-Disposition: attachment; filename={output-filename.pdf}
Content-Type: {content-type}
Content-Length: {content-length}
Gotenberg-Trace: {trace}
Body: {output-file}

400

The request had one ore more invalid form fields.

Content-Type: text/plain; charset=UTF-8
Gotenberg-Trace: {trace}
Body: {error}

503

The request did not complete within the configured maximum duration.

Content-Type: text/plain; charset=UTF-8
Gotenberg-Trace: {trace}
Body: Service Unavailable

Rendering Behavior

Layout & Pages

Form Fields

landscapeboolean

Sets the paper orientation to landscape.

Default:false

singlePageSheetsboolean

Ignores each sheet’s paper size, print ranges and shown/hidden status and puts every sheet (even hidden sheets) on exactly one page.

Default:false

skipEmptyPagesboolean

Suppresses automatically inserted empty pages. Active only for Writer documents.

Default:false

exportPlaceholdersboolean

Exports placeholder fields as visual markings only (non-functional).

Default:false

Example Request

cURL

curl \
--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.

Form Fields

losslessImageCompressionboolean

Uses lossless (PNG) compression instead of lossy (JPEG) for images.

Default:false

qualityinteger

JPEG export quality. Higher values produce better quality but larger files. Between 1 and 100.

Default:90

reduceImageResolutionboolean

Reduces each image to the resolution specified by maxImageResolution.

Default:false

maxImageResolutioninteger

Target resolution in DPI when reduceImageResolution is true. Possible values: 75, 150, 300, 600, 1200.

Default:300

Example Request

cURL

curl \
--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

Form Fields

exportNotesboolean

Exports notes to PDF.

Default:false

exportNotesPagesboolean

Exports notes pages to PDF. Available in Impress documents only.

Default:false

exportOnlyNotesPagesboolean

When exportNotesPages is true, exports only the notes pages.

Default:false

exportNotesInMarginboolean

Exports notes in margin to PDF.

Default:false

exportHiddenSlidesboolean

Exports Impress slides that are not included in slide shows.

Default:false

Links

Form Fields

convertOooTargetToPdfTargetboolean

Changes .od[tpgs] extensions to .pdf in exported links. The source document remains untouched.

Default:false

exportLinksRelativeFsysboolean

Exports file:// hyperlinks as relative to the source document location.

Default:false

Macros

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.

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.

Form Fields

updateIndexesboolean

Updates indexes (e.g., Table of Contents) before conversion. May cause missing links.

Default:true

exportBookmarksboolean

Exports bookmarks to the PDF.

Default:true

exportBookmarksToPdfDestinationboolean

Exports bookmarks as Named Destinations.

Default:false

addOriginalDocumentAsStreamboolean

Embeds the original document as a stream in the PDF for archiving.

Default:false

Example Request

cURL

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

Native Flattening (LibreOffice)

Set exportFormFields to false to prevent LibreOffice from creating interactive PDF widgets, effectively flattening them during conversion. Faster than post-processing.

Form Fields

exportFormFieldsboolean

Exports form fields as interactive widgets. Set to false to flatten them during conversion.

Default:true

allowDuplicateFieldNamesboolean

Allows multiple exported form fields to share the same field name.

Default:false

Example Request

cURL

curl \
--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.

Form Fields

metadatajson

Writes metadata (Author, Title, etc.).

Default:None

Example Request

cURL

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)

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.

Form Files

embedsfile[]

Embeds files into the PDF.

Default:None

Example Request

cURL

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

Flatten (PDF Engines)

Merges all interactive form fields (text inputs, checkboxes, etc.) into the page content, making the PDF non-editable.

Form Fields

flattenboolean

Converts form fields into static content, preventing further editing.

Default:false

Example Request

cURL

curl \
--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).

Form Files

mergeboolean

Merge the resulting PDFs.

Example Request

cURL

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.

Form Fields

nativePageRangesstring

Page ranges to print, e.g., '1-4'. Empty means all pages. Applied independently to each file.

Default:All pages

Example Request

cURL

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)

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 Configuration to see which engine is active.

Form Fields

splitModeenum

Either 'intervals' or 'pages'. Configures how the PDF should be split.

Default:None

splitSpanstring

The intervals or page ranges to extract, based on the splitMode.

Default:None

splitUnifyboolean

If true, puts extracted pages into a single file. Only works with 'pages' mode.

Default:false

Example Request

cURL

curl \
--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.

Form Fields

nativeWatermarkTextstring

A single-line text watermark rendered behind the document content.

Default:None

nativeWatermarkColorinteger

The color of the native watermark text as a decimal RGB value (e.g., 16711680 for red).

Default:8388223

nativeWatermarkFontHeightinteger

The font height (size) in points. 0 means auto-sized.

Default:0

nativeWatermarkRotateAngleinteger

The rotation angle in tenths of a degree (e.g., 450 = 45°).

Default:0

nativeWatermarkFontNamestring

The font name for the watermark text (e.g., 'Times New Roman').

Default:Helvetica

nativeTiledWatermarkTextstring

A tiled (repeating) text watermark rendered behind the document content.

Default:None

Example Request

cURL

curl \
--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)

Form Fields

watermarkSourceenum

The watermark source type. Options: 'text', 'image', 'pdf'.

Default:None

watermarkExpressionstring

The watermark content. For 'text', the string to render. For 'image' or 'pdf', the filename of the uploaded watermark file.

Default:None

watermarkPagesstring

Page ranges to watermark (e.g., '1-3', '5'). Empty means all pages.

Default:None

watermarkOptionsjson

Advanced watermark options in JSON format (e.g., font, color, rotation, opacity, scaling).

Default:None

Form Files

watermarkfile

An image or PDF file used as watermark source.

Default:None

Example Request

cURL

curl \
--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)

Form Fields

stampSourceenum

The stamp source type. Options: 'text', 'image', 'pdf'.

Default:None

stampExpressionstring

The stamp content. For 'text', the string to render. For 'image' or 'pdf', the filename of the uploaded stamp file.

Default:None

stampPagesstring

Page ranges to stamp (e.g., '1-3', '5'). Empty means all pages.

Default:None

stampOptionsjson

Advanced stamp options in JSON format (e.g., font, color, rotation, opacity, scaling).

Default:None

Form Files

stampfile

An image or PDF file used as stamp source.

Default:None

Example Request

cURL

curl \
--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.

Form Fields

rotateAngleenum

The rotation angle. Options: '90', '180', '270'.

rotatePagesstring

Page ranges to rotate (e.g., '1-3', '5'). Empty means all pages.

Example Request

cURL

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.

Form Fields

pdfaenum

Converts to a specific PDF/A archival standard. Options: 'PDF/A-1b', 'PDF/A-2b', 'PDF/A-3b'.

Default:None

pdfuaboolean

Enables PDF/UA (Universal Accessibility) compliance.

Default:false

Example Request

cURL

curl \
--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

Form Fields

passwordstring

LibreOffice feature. The password for opening the source file.

Default:None

userPasswordstring

The password required to open the PDF.

Default:None

ownerPasswordstring

The password required to change permissions or edit the PDF.

Default:None

Open Document (LibreOffice)

Use the password form field if the source file is password-protected.

Example Request

cURL

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)

Set passwords to control PDF access. The user password is required to open the PDF; the owner password controls permissions (printing, copying, editing).

Encryption strength (e.g., AES-256) depends on the active PDF Engine. See PDF Engines Configuration.

Example Request

cURL

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

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.

Form Fields

initialViewinteger

Initial view when opening the PDF. 0: neither document outline nor thumbnails. 1: document outline visible. 2: thumbnail images visible.

Default:0

initialPageinteger

The page on which the PDF opens.

Default:1

magnificationinteger

Initial magnification level. 0: default. 1: fit page. 2: fit width. 3: fit visible. 4: use zoom value.

Default:0

zoominteger

Initial zoom percentage when magnification is set to 4.

Default:100

pageLayoutinteger

Page layout. 0: default. 1: single page. 2: one column. 3: two columns.

Default:0

firstPageOnLeftboolean

Place the first page on the left when using two-column page layout.

Default:false

resizeWindowToInitialPageboolean

Resize the viewer window to the size of the first page.

Default:false

centerWindowboolean

Center the viewer window on the screen.

Default:false

openInFullScreenModeboolean

Open the PDF in full-screen mode.

Default:false

displayPDFDocumentTitleboolean

Display the document title in the viewer title bar instead of the filename.

Default:true

hideViewerMenubarboolean

Hide the viewer menu bar.

Default:false

hideViewerToolbarboolean

Hide the viewer toolbar.

Default:false

hideViewerWindowControlsboolean

Hide the viewer window controls.

Default:false

useTransitionEffectsboolean

Use transition effects when advancing slides in Impress presentations.

Default:true

openBookmarkLevelsinteger

Number of bookmark levels to show when opening the PDF. -1 shows all levels.

Default:-1

Example Request

cURL

curl \
--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

Sponsors

Powered by

❤️ Become a sponsor