unoserver

3.6 · active · verified Fri Apr 17

Unoserver provides a server for performing file conversions using LibreOffice or OpenOffice. It allows Python applications to convert various document types (e.g., DOCX, XLSX, ODT) to other formats (e.g., PDF) by interacting with a running LibreOffice instance via a network socket. The current version is 3.6, with development actively maintained on GitHub.

Common errors

```
FileNotFoundError: [Errno 2] No such file or directory: 'soffice'
```
cause LibreOffice/OpenOffice is not installed or its executable (`soffice`) is not found in the system's PATH on the machine running `unoserver`.

fix Install LibreOffice or OpenOffice. Verify it's in the system's PATH, or start `unoserver` with the `--uno-interface` option pointing to the `soffice` executable (e.g., `unoserver --uno-interface 'socket,host=127.0.0.1,port=2002;urp;StarOffice.ServiceManager;/usr/lib/libreoffice/program/soffice.bin'`).
```
unoserver.exceptions.UnoServerError: Could not connect to UnoServer at 127.0.0.1:2002
```
cause The `unoserver` process is not running, is running on a different host/port, or a firewall is blocking the connection.

fix Ensure `unoserver` is running (e.g., `unoserver --log-level INFO` in a terminal). Verify the host and port match between the server startup command and the client `UnoConverter` instantiation. Check firewall settings.
```
AttributeError: module 'unoserver' has no attribute 'unoconvert'
```
cause Attempting to use old `unoconv` library syntax with `unoserver`. The `unoserver` library has a different API based on its client-server model.

fix Refactor your code to use the `unoserver.converter.UnoConverter` class. The `unoconvert` function does not exist in `unoserver`.

Warnings

breaking Users migrating from the older `unoconv` Python library to `unoserver` will encounter significant breaking changes. `unoserver` fundamentally redesigns the conversion process around a client-server architecture, meaning direct function calls like `unoconv.unoconvert()` no longer exist.
Fix: Rewrite conversion logic to use `unoserver.converter.UnoConverter` to connect to a running `unoserver` instance. Start `unoserver` as a separate process via the command line or `unoserver.start()`.
gotcha Unoserver requires LibreOffice or OpenOffice to be installed on the machine where the `unoserver` process is running. If LibreOffice is not found in the system's PATH, the server will fail to start or conversions will error out.
Fix: Install LibreOffice/OpenOffice on the server machine. Ensure its executable (`soffice` or similar) is accessible via the system's PATH or specify its path using the `--interface` option when starting `unoserver`.
gotcha The default port for unoserver is 2002. If another application is using this port, or if you attempt to run multiple unoserver instances on the same port, connection errors will occur. Firewalls can also block connections.
Fix: Change the default port using the `--port` option when starting `unoserver` (e.g., `unoserver --port 2003`). Ensure your client code connects to the correct port. Check firewall rules if connections are refused.

Install

pip install unoserver Install unoserver client library

Imports

UnoConverter
```
from unoserver.converter import UnoConverter
```
Primary class for client-side file conversions.
start
wrong:
```
from unoserver.server import start
```
correct:
```
from unoserver import start
```
Function to programmatically start the unoserver process. While possible, starting via CLI (`unoserver`) is often preferred for deployment.

Quickstart

This quickstart demonstrates how to use the `UnoConverter` client to connect to a running `unoserver` instance and convert a dummy text file to PDF. It assumes that the `unoserver` command-line tool is already active in a separate process and that LibreOffice is installed on the server machine. The example creates a temporary input file and cleans up afterwards.

import os
from unoserver.converter import UnoConverter

# NOTE: For this code to run, the `unoserver` command-line tool
# must be running in a separate process, e.g., via `unoserver --log-level INFO`.
# LibreOffice must also be installed on the server machine.

# Create a dummy input file
dummy_input_path = 'dummy_input.txt'
with open(dummy_input_path, 'w') as f:
    f.write('Hello, UnoServer! This is a test document.')

try:
    with UnoConverter() as converter:
        # Convert the dummy text file to PDF
        output_path = converter.convert(dummy_input_path, 'dummy_output.pdf')
        print(f"Successfully converted '{dummy_input_path}' to '{output_path}'")
except Exception as e:
    print(f"Error during conversion: {e}")
    print("Ensure `unoserver` is running and LibreOffice is installed.")
finally:
    # Clean up dummy files
    if os.path.exists(dummy_input_path):
        os.remove(dummy_input_path)
    if os.path.exists('dummy_output.pdf'): # Check if conversion actually created it
        os.remove('dummy_output.pdf')

view raw JSON →