LibreOffice headless convert CLI guide

The common command is soffice --headless --convert-to pdf --outdir out input.docx. For DOC to DOCX, use soffice --headless --convert-to docx --outdir out input.doc. LibreOffice chooses an import filter from the input and an export filter from the requested output.

Run from a directory where the output folder exists or can be created. In scripts, check both the exit code and the expected output file. Some failures produce console warnings but still return a file that needs inspection.

--convert-to accepts a target extension and, when needed, a filter name. Most simple exports work with only the extension. More specialized PDF options may need filter data that is easier to manage through a service wrapper than a raw shell command.

LibreOffice supports many Office and OpenDocument formats, but support is not identical for every feature. DOCX text, tables, and common images are usually handled better than macros, embedded OLE objects, complex SmartArt, or unusual form controls.

Headless conversion uses fonts installed on the machine. If a DOCX was designed with Calibri, Aptos, Times New Roman, or a corporate font that is missing on the server, LibreOffice substitutes another font. That can change line breaks, page count, and table overflow.

For batch conversion, install the expected fonts legally and keep the container image stable. Then test representative files, not just a one-page sample. Font substitution is one of the main reasons a file converts cleanly but looks different.

LibreOffice writes to a user profile even in headless mode. Parallel conversions sharing one profile can lock or interfere with each other. Server deployments often create isolated temporary profiles per worker or run conversions through a controlled sidecar.

Do not point headless conversion at a profile used by a desktop LibreOffice session. A locked profile can hang automation or produce confusing errors. Use a dedicated conversion user or profile directory.

After conversion, compare page count, headings, tables, images, headers, footers, comments, and tracked changes. For spreadsheets, check sheet selection, print areas, hidden sheets, and page scaling. For presentations, check fonts and slide backgrounds.

LibreOffice is useful for automation, but it is not Microsoft Word running invisibly. If exact Word rendering is contractually required, use Word in a licensed environment or make PDF from the source application.

Containerized conversion should pin the LibreOffice version and installed fonts. Otherwise a routine image rebuild can change pagination across thousands of outputs. Keep a small fixture set and compare rendered PDFs after dependency updates.

When converting untrusted documents, isolate the process. Headless mode removes the graphical interface, but it does not make arbitrary documents safe. Run with limited filesystem access, no production secrets, and resource limits appropriate for large or malformed files.

For spreadsheets, decide the sheet policy before export. A PDF can include only selected sheets, all sheets, or print ranges depending on document settings and filters. Batch jobs should log which sheets were rendered so omissions can be traced.

Keep stderr and stdout from failed conversions. Warning text often names the missing filter, locked profile, or font substitution that caused the visible defect.

A final automation design should queue conversions rather than starting unlimited soffice processes. Office documents can be large and slow, and resource limits protect the rest of the application.

For slides, review speaker notes separately. PDF export usually renders slides, not a complete presentation review package.