JODConverter: Java document conversion with LibreOffice

JODConverter's Java conversion role

JODConverter targets applications that must convert documents between office formats as normal application work. The project supports Word, Excel, PowerPoint, OpenDocument, PDF, HTML, images, and other formats accepted by the installed office suite. It is intended for developers building Java services, Spring Boot applications, or command-line workflows rather than users who need a desktop conversion interface.

The project offers three documented entry points. Developers can add `jodconverter-local-lo` as a Java or Kotlin dependency, install `jodconverter-spring-boot-starter` for Spring Boot configuration, or download `jodconverter-cli` from the latest GitHub release. This makes the same conversion capability available inside an application, through framework injection, or from a shell script.

JODConverter does not implement each office format independently. According to the README, it drives a LibreOffice or Apache OpenOffice installation and converts whatever that office product converts. That distinction matters during adoption: supported output depends partly on the selected office suite and its installation, not only on JODConverter's own API.

Local office manager and conversion flow

The quick-start design centers on an office manager. `LocalOfficeManager.install()` locates a LibreOffice installation in its default location, `start()` launches the office process, and the manager remains available for subsequent conversions. The example converts `document.docx` into `document.pdf` with a chained call from `JodConverter.convert(source).to(target).execute()`.

The code explicitly stops the manager in a `finally` block through `OfficeUtils.stopQuietly`. That pattern makes cleanup part of the conversion example rather than leaving it as an optional operational detail. It also distinguishes conversion execution from office-process lifetime.

The README says an office manager should live as long as the application and be shared by all conversions. Its stated reason is operational: starting an office process costs much more than performing a conversion. A service that launches LibreOffice for each request would therefore misuse the documented lifecycle. A long-lived application should create the manager once and coordinate access to it, although the README does not provide concurrency guidance for this scenario.

The repository layout also shows local LibreOffice and OpenOffice modules, a remote module, a core module, a CLI, and a Spring Boot starter. The README additionally documents conversion through LibreOffice Online or Collabora Online. These modules indicate that the conversion API can sit above different execution locations, while the quick start specifically exercises the local LibreOffice path.

Installing JODConverter 5.1.1 and converting a DOCX

JODConverter 5.x requires Java 17 or later and a LibreOffice installation on the machine that performs conversion, or Apache OpenOffice as the alternative. The README recommends LibreOffice. For a Kotlin or Gradle-style project, the documented local LibreOffice dependency is:

implementation("org.jodconverter:jodconverter-local-lo:5.1.1")

For Maven, the README provides an XML dependency declaration. The application can then start the office manager, convert a file, and close the manager after its conversion work. The documented Java flow is:

LocalOfficeManager officeManager = LocalOfficeManager.install();
try {
  officeManager.start();
  JodConverter.convert(new File("document.docx")).to(new File("document.pdf")).execute();
}
finally {
  OfficeUtils.stopQuietly(officeManager);
}

The source and target names imply the expected first use: an existing `document.docx` is read and `document.pdf` is produced. The exact exception handling and complete class declarations are included in the README example, so the abbreviated block here does not replace the full sample.

For script use without writing Java, the project directs users to download `jodconverter-cli` from the latest release and unpack it. On a Unix-like shell, the documented command is:

bin/jodconverter-cli document.docx document.pdf

Windows users are directed to `bin\jodconverter-cli.bat`. The README does not document CLI installation through a package manager, so an automated deployment should package or fetch the release artifact itself.

Spring Boot integration for injected conversions

The Spring Boot path avoids constructing the local manager in each service. The README says to add the starter alongside the local LibreOffice library. For a Kotlin build, the two documented dependencies are:

implementation("org.jodconverter:jodconverter-spring-boot-starter:5.1.1")
implementation("org.jodconverter:jodconverter-local-lo:5.1.1")

The starter is enabled through the `jodconverter.local.enabled` property. Once enabled, application code injects `DocumentConverter` into a service and submits a source and target through `converter.convert(source).to(target).execute()`.

That division makes the starter useful when conversion is one responsibility among several Spring-managed components. It also leaves infrastructure startup and configuration with the starter rather than embedding it in a `ReportService`. The README does not describe manager shutdown for Spring Boot, shutdown exceptions, concurrency controls, or complete bean customization, so those details need to come from the linked configuration documentation before production integration.

The property also shows that local conversion is opt-in in the documented Spring setup. An application that adds the dependencies but leaves local conversion disabled should not expect the injected service to start a local LibreOffice process. The README does not define a remote equivalent property.

Format support, PDF controls, and deployment boundaries

JODConverter exposes the formats available through the underlying office product. The README lists common office documents, OpenDocument, PDF, HTML, and images, but it also states that conversion reaches whatever LibreOffice or OpenOffice converts. This offers broad format coverage, yet it is not a guarantee that layout-sensitive files will translate without differences. Neither the README nor the repository layout defines a fidelity matrix for fonts, complex spreadsheets, macros, forms, or embedded objects.

For PDF output, the documentation links to options for PDF/A, PDF/UA, passwords, watermarks, and signatures. Those controls matter for generated reports and regulated document workflows, but the README does not say whether every option applies equally to every input format or office implementation. The PDF options documentation is the place to verify version and configuration requirements.

Deployment is another boundary. The local module needs office software installed on the converting machine. The repository also contains a remote module, and the documentation describes LibreOffice Online and Collabora Online integration. The README does not specify remote endpoints, authentication settings, deployment examples, or retry behavior. A container image therefore needs its own office installation and configuration, while a hosted conversion architecture requires details beyond the quick start.

The project also does not document rollback or conversion auditing in the README. Applications that need those guarantees must add their own storage, policy, and operational controls rather than infer them from the conversion API.

JODConverter maintenance and Apache-2.0 implications

The repository is not archived. Its last push was on 2026-10-15, and the recent release history includes v5.1.1 on 2026-10-15, v5.1.0 on 2026-10-12, and v5.0.1 on 2026-10-08. These dates show recent release activity around the 5.x line. They do not establish compatibility with every document type or remove the cost of testing upgrades.

The compatibility table in the README creates a clear upgrade boundary. JODConverter 5.x requires Java 17 or later and is paired with Spring Boot 4.x. JODConverter 4.4.x uses Java 8 or later and Spring Boot 2.x and 3.x. Projects moving from 4.4 are directed to the migration guide for 5.0.0. An adoption decision should therefore include the runtime upgrade if the existing service still targets an older Java release.

Release frequency does not remove document-level regression work. Because output is produced by an office suite, changing JODConverter, LibreOffice, OpenOffice, fonts, or input files can affect results. The repository's release notes and project documentation are the appropriate places to check specific changes, but the README does not define a compatibility matrix for office-suite versions.

JODConverter is licensed under the Apache License, Version 2.0. The repository includes `LICENSE` and `NOTICE` files. That identifies the project's license, while application owners remain responsible for reviewing their dependencies and license obligations. This is not legal advice.

JODConverter versus direct office conversion

The closest architectural alternative is invoking LibreOffice or Apache OpenOffice directly from application code without JODConverter. That approach leaves the developer responsible for locating the office executable, starting and stopping the process, translating command-line or API arguments, handling file state, and exposing a conversion interface to the rest of the application. JODConverter packages those concerns into Java modules, an office manager lifecycle, a fluent converter API, a Spring Boot starter, and a CLI distribution.

Another documented choice is converting through LibreOffice Online or Collabora Online instead of running office software locally. The architectural difference is placement. A local manager controls an office process on the conversion host. A remote setup sends conversion work to a separate service, which may suit deployments where installing office software on each application host is undesirable. The README does not document remote configuration details, so it supports recognition of the option rather than a complete comparison.

JODConverter is the wrong choice when deployment cannot provide Java 17, cannot install or reach an office implementation, or needs a conversion engine with a fully independent fidelity contract. It is also a poor fit for a one-off manual conversion, since users can operate LibreOffice directly without adding a Java dependency. For an existing Java application that already depends on office automation, the library offers a narrower interface and a shared process lifecycle.

Editorial conclusion

Adopt JODConverter when a Java service needs ongoing document conversion and LibreOffice or OpenOffice is an acceptable runtime dependency. Do not choose it as a self-contained formatter or for deployments that cannot host or reach an office installation. Verify conversion fidelity with representative documents, confirm the required office installation and Java version, and inspect the documented manager configuration before upgrading across major versions.

Frequently asked questions

Official sources

1. jodconverter/jodconverter on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases