Skip to main content
Version: 7.x

LibreOffice

The LibreOffice module interacts with LibreOffice to convert documents to PDF, thanks to unoconv.

Properties

--libreoffice-disable-routes     bool      Disable the routes
--uno-listener-start-timeout duration Time limit for starting the LibreOffice listener (default 10s)
--uno-listener-restart-threshold int Conversions limit after which the LibreOffice listener is restarted - 0 means no long-running LibreOffice listener (default 10)
tip

By default, a long-running LibreOffice listener handles the conversions. This stateful mode allows for faster unitary conversion, but there is a lock mechanism as a single LibreOffice listener cannot perform parallel operations.

In other words, under heavy load, you should consider scaling up your number of Gotenberg instances or switch the LibreOffice module to a stateless mode with --uno-listener-restart-threshold=0 (i.e., a dedicated LibreOffice listener per conversion).

info

Gotenberg restarts the long-running LibreOffice listener if it is unhealthy before and after a conversion.

caution

The --uno-* properties also impact the performance of the UNO PDF engine.

caution

The property --unoconv-disable-listener is deprecated in favor of --uno-listener-restart-threshold with 0 as value.

Route

POST /forms/libreoffice/convert

This route accepts multipart/form-data requests and files with the following extensions:

.bib  .doc  .xml  .docx  .fodt  .html  .ltx  .txt  .odt  .ott  .pdb  .pdf  .psw  .rtf  .sdw  .stw  .sxw  .uot  .vor  .wps  .epub  .png  .bmp  .emf  .eps  .fodg  .gif  .jpg  .met  .odd  .otg  .pbm  .pct  .pgm  .ppm  .ras  .std  .svg  .svm  .swf  .sxd  .sxw  .tiff  .xhtml  .xpm  .fodp  .potm  .pot  .pptx  .pps  .ppt  .pwp  .sda  .sdd  .sti  .sxi  .uop  .wmf  .csv  .dbf  .dif  .fods  .ods  .ots  .pxl  .sdc  .slk  .stc  .sxc  .uos  .xls  .xlt  .xlsx  .tif  .jpeg  .odp

For instance:

curl \
--request POST 'http://localhost:3000/forms/libreoffice/convert' \
--form 'files=@"/path/to/file.docx"' \
-o my.pdf
curl \
--request POST 'http://localhost:3000/forms/libreoffice/convert' \
--form 'files=@"/path/to/file.docx"' \
--form 'files=@"/path/to/file.xlsx"' \
-o my.zip
landscape bool  Set the paper orientation to landscape (default false)

For instance:

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

Health Check

If --uno-listener-restart-threshold=0 (i.e., stateless mode), there is no health check.

In stateful mode, the health route returns a 503 Service Unvailable response if the long-running LibreOffice listener is unhealthy.

info

Gotenberg considers a restarting long-running LibreOffice listener healthy.

Switch Language

By default, LibreOffice uses the English language when it converts documents to PDF. You may override this behavior by building your own Docker image.

For instance, with the German language:

FROM gotenberg/gotenberg:7

USER root

RUN apt-get update -qq &&\
DEBIAN_FRONTEND=noninteractive apt-get install -y -qq --no-install-recommends -t bullseye-backports libreoffice-l10n-de &&\
sed -i '/de_DE.UTF-8/s/^# //g' /etc/locale.gen &&\
locale-gen &&\
# Cleanup.
# Note: the Debian image does automatically a clean after each install thanks to a hook.
# Therefore, there is no need for apt-get clean.
# See https://stackoverflow.com/a/24417119/3248473.
rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*

ENV LANG de_DE.UTF-8
ENV LANGUAGE de_DE:de
ENV LC_ALL de_DE.UTF-8

USER gotenberg

Metrics

The LibreOffice module exposes the following metrics:

  • {namespace}_unoconv_active_instances_count - current number of active unoconv instances.
  • {namespace}_libreoffice_listener_active_instances_count - current number of active LibreOffice listener instances.
  • {namespace}_libreoffice_listener_queue_length - current number of processes in the LibreOffice listener queue.
caution

The metrics unoconv_listener_active_instances_count and unoconv_listener_queue_length are deprecated in favor of libreoffice_listener_active_instances_count and libreoffice_listener_queue_length.

See Prometheus for more details.

Troubleshooting

Filename contains non-Latin characters

convert to PDF: unoconv PDF: unix process error: wait for unix process: exit status 6

Make sure the filename is UTF-8 encoded. See issue #427 for more details.

Troublesome .pptx file

If you keep getting 500 Internal Server Error while trying to convert a .pptx file, a common workaround is to increase the memory and CPU available to Gotenberg. See issue #465 for more details.