Last updated: February 5, 2025

<span aria-hidden="true" id="unoconv-for-document-conversion-ease"></span>

# 'unoconv' for document conversion ease

![Kevin van Zonneveld](/assets/images/teammates/avatar-kvz-4.jpg?dpl=dpl_BY7TrZQKuzkQ5PseorQMAAVfrV9b)

#### Kevin van Zonneveld

Co-founder · Amsterdam, The Netherlands · Show bio

[](https://x.com/kvz)[](https://github.com/kvz)

Converting documents between different formats is a common task for developers and professionals. Historically, [unoconv⁠](https://github.com/unoconv/unoconv) served as an open-source tool that leveraged LibreOffice to convert documents such as DOCX, ODT, and XLSX to PDF and other formats.

###### Important

Unoconv is officially deprecated and now maintained only for legacy support. For all new implementations, please use [unoserver⁠](https://github.com/unoconv/unoserver/), the modern successor with better Python 3 compatibility and improved performance. This post is maintained for historical reference and for those supporting existing unoconv workflows.

<span aria-hidden="true" id="introduction-to-unoconv-and-its-open-source-capabilities"></span>

## Introduction to 'unoconv' and its open-source capabilities

'Unoconv' (Universal Office Converter) is a command-line utility that leverages[LibreOffice⁠](https://www.libreoffice.org/) for document conversion. It supports a wide range of document formats, making it useful for developers maintaining legacy systems or supporting existing workflows. Although unoconv is deprecated, it serves as an instructive example of automating document conversion tasks.

<span aria-hidden="true" id="setting-up-and-installing-unoconv-on-your-system"></span>

## Setting up and installing 'unoconv' on your system

<span aria-hidden="true" id="prerequisites"></span>

### Prerequisites

Before using 'unoconv', ensure that LibreOffice is installed on your system since unoconv relies on it for performing conversions. Be aware that unoconv may have compatibility issues with modern Python versions—consider switching to [unoserver⁠](https://github.com/unoconv/unoserver/) for new projects.

<span aria-hidden="true" id="installation-on-linux-ubuntudebian"></span>

### Installation on Linux (Ubuntu/Debian)

Update your package list and install LibreOffice and unoconv using apt:

```bash
sudo apt-get update
sudo apt-get install libreoffice unoconv

```

###### Note

On modern systems, you might encounter Python version conflicts. For new implementations, consider using unoserver instead.

<span aria-hidden="true" id="installation-on-macos"></span>

### Installation on macOS

macOS users can install unoconv via Homebrew. However, Python version conflicts may occur, so for new setups, using unoserver is advised. To install an existing unoconv setup:

```bash
brew install --cask libreoffice
brew install unoconv

```

<span aria-hidden="true" id="installation-on-windows"></span>

### Installation on Windows

Native Windows support for unoconv is limited. We recommend using Windows Subsystem for Linux (WSL2) and following the Linux installation instructions to ensure compatibility.

<span aria-hidden="true" id="common-use-cases-and-scenarios"></span>

## Common use cases and scenarios

Developers can employ unoconv for various tasks, including:

* **Batch Conversions:** Convert multiple DOCX files to PDF in a single operation.
* **Automating Report Generation:** Automatically generate PDF reports from document templates.
* **Legacy System Maintenance:** Support and maintain workflows that still depend on unoconv.
* **Server-Side Processing:** Integrate document conversion into back-end applications for automated processing.

<span aria-hidden="true" id="step-by-step-guide-converting-documents-from-docx-to-pdf"></span>

## Step-by-step guide: converting documents from docx to PDF

Basic conversion using unoconv is straightforward. To convert a single DOCX file to PDF, execute:

```bash
unoconv -f pdf document.docx

```

For batch conversion of multiple DOCX files:

```bash
unoconv -f pdf *.docx

```

<span aria-hidden="true" id="automating-document-conversion-tasks-with-scripts"></span>

## Automating document conversion tasks with scripts

Automating document conversion can streamline your workflow. The following Python script demonstrates how to convert DOCX files to PDF with proper error handling:

```python
import subprocess
import os
import sys


def convert_documents(input_dir, output_dir):
    os.makedirs(output_dir, exist_ok=True)

    for filename in os.listdir(input_dir):
        if filename.endswith('.docx'):
            input_path = os.path.join(input_dir, filename)
            output_filename = os.path.splitext(filename)[0] + '.pdf'
            output_path = os.path.join(output_dir, output_filename)

            try:
                subprocess.run(
                    ['unoconv', '-f', 'pdf', '-o', output_path, input_path],
                    capture_output=True,
                    text=True,
                    check=True
                )
                print(f'Converted {input_path} to {output_path}')
            except subprocess.CalledProcessError as e:
                print(f'Error converting {input_path}: {e.stderr}', file=sys.stderr)
            except Exception as e:
                print(f'Unexpected error while processing {input_path}: {e}', file=sys.stderr)


if __name__ == '__main__':
    convert_documents('docs', 'pdfs')

```

<span aria-hidden="true" id="troubleshooting-common-issues"></span>

## Troubleshooting common issues

<span aria-hidden="true" id="python-version-conflicts"></span>

### Python version conflicts

Modern systems might present Python version conflicts with unoconv. To resolve these issues, you can:

* Use a Python virtual environment with a compatible version.
* Install a specific Python version that works well with unoconv.
* Switch to using unoserver, which offers better Python 3 compatibility.

<span aria-hidden="true" id="libreoffice-version-compatibility"></span>

### Libreoffice version compatibility

Ensure your LibreOffice installation is compatible with unoconv:

```bash
libreoffice --version
unoconv --version

```

<span aria-hidden="true" id="container-deployment-considerations"></span>

### Container deployment considerations

For containerized environments, consider the following:

* Use official LibreOffice base images.
* Ensure necessary fonts are installed.
* Configure appropriate file permissions.

These steps help prevent errors during document conversion in container deployments.

<span aria-hidden="true" id="modern-alternatives-and-comparison"></span>

## Modern alternatives and comparison

<span aria-hidden="true" id="unoserver-recommended"></span>

### Unoserver (recommended)

Unoserver is the modern successor to unoconv. It offers improved performance, active maintenance, and robust error handling with full Python 3 compatibility. For new projects, adopting unoserver is the recommended approach.

<span aria-hidden="true" id="libreoffice-cli"></span>

### Libreoffice CLI

LibreOffice itself provides a native command-line conversion option that bypasses the need for unoconv. To convert a DOCX file to PDF using LibreOffice CLI, run:

```bash
soffice --headless --convert-to pdf document.docx

```

<span aria-hidden="true" id="cloud-based-solutions"></span>

### Cloud-based solutions

For scalable production environments, consider cloud-based document conversion services or containerized solutions that provide enhanced reliability and effortless maintenance.

<span aria-hidden="true" id="conclusion"></span>

## Conclusion

Although unoconv has served developers well over the years, its deprecation means that new projects should consider modern alternatives like unoserver or cloud-based conversion services. For those maintaining legacy systems, be mindful of compatibility and potential Python version issues.

If you are seeking a robust, scalable solution for document conversion, consider exploring[Transloadit's Document Conversion service](/docs/robots/document-convert.md).

\#unoconv#document-conversion#open-source-tool#convert-docx-to-pdf#automate-document-conversion#document-processing-service

### 👩‍💻 Join 20k+ developers

Sign up for our [monthly newsletter](/newsletters.md) to receive direct links to 3 exclusive tech — and 2 product updates. No less, no more.

Your email:

Get access

## File uploading and encoding. Made simple.

Transloadit streamlines file handling for developers, trusted by brands like Coursera and The New York Times. We’re known for a reliable API, top-notch support, and a strong commitment to open source, with projects like [Uppy⁠](https://uppy.io) and [Tus⁠](https://tus.io) setting standards in file processing.

[Sign up](/c/)[Book a Demo](https://survey.typeform.com/to/kRg47Xi5)

No credit card needed · 5 GB included in the free plan

Cancel anytime