unoserver Documentation

Standard LibreOffice conversion (e.g., libreoffice --headless --convert-to pdf ...) loads LibreOffice into memory, performs the conversion, and then exits. This causes high CPU overhead when converting many documents because the software must be reloaded for every file.

unoserver solves this by using LibreOffice's listener mode. The unoserver command starts a listener on a specified IP and port. This allows the software to stay loaded in memory, accepting multiple conversion requests via a client (unoconverter or unocompare) without exiting and reloading. This can reduce CPU load by 50% to 75% and increase conversion throughput by 2x to 4x.

Releases are managed using zest.releaser. Before running the release process, ensure you have a valid .pypirc file configured for uploading packages to PyPI. Use the fullrelease command to start the guided release, packaging, and upload process.

$ fullrelease

To set up a development environment for unoserver, clone the repository and create a virtual environment using the --system-site-packages flag. This flag is required to ensure the virtual environment can access the uno library, which relies on a system-level LibreOffice installation using the system Python.

After creating the environment, install the package in editable mode with the [devenv] extra to include development dependencies.

$ git clone git@github.com:unoconv/unoserver.git
$ cd unoserver
$ virtualenv ve --system-site-packages
$ ve/bin/pip install -e .[devenv]

To install unoserver on Unix, use pip. Note that unoserver must be installed using the same Python installation that LibreOffice uses to ensure the unoserver command can access the necessary LibreOffice libraries.

If you have a standard system installation:

sudo -H pip install unoserver

If you have multiple LibreOffice versions or a specific LibreOffice distribution, you must run pip using that specific Python executable:

sudo -H /full/path/to/python -m pip install unoserver

To find all Python installations that have the relevant LibreOffice libraries installed, you can use the find_uno.py script:

wget -O find_uno.py https://gist.githubusercontent.com/regebro/036da022dc7d5241a0ee97efdf1458eb/raw/find_uno.py
python3 find_uno.py

If you are using the system Python for your virtual environment, you must include the --system-site-packages flag so the environment can access the LibreOffice libraries installed on the system.

virtualenv --python=/usr/bin/python3 --system-site-packages virtenv
virtenv/bin/pip install unoserver

You can execute the project's test suite using the provided Makefile shortcut.

$ make test

Use unoconvert to transform files using a running unoserver. You can pass specific filter options to control the output format.

Set PNG dimensions:

unoconvert infile.odt outfile.png --filter-options PixelWidth=640 --filter-options PixelHeight=480

Set CSV output options:

unoconvert infile.xlsx outfile.csv --filter-options "59,34,76,1"

Export HTML with embedded images:

unoconvert infile.odt outfile.html --filter-options EmbedImages

Use unoping to verify if a unoserver instance is up and running. It will print the versions of the server components.

unoping [-h] [-v] [--host HOST] [--port PORT] [--protocol {http,https}] [--verbose | --quiet] [-f LOGFILE]