Universal Office Converter (unoconv) is a command line tool to convert any document format that LibreOffice can import to any document format that LibreOffice can export. It makes use of the LibreOffice’s UNO bindings for non-interactive conversion of documents.
For practical reasons we mention LibreOffice, but OpenOffice is supported by unoconv as well.
unoconv starts its own office instance (if it cannot find an existing listener) that it then uses. There are some challenges to do this correctly, but in general this works fine.
Typically you would convert an ODT document to PDF by running:
unoconv -f pdf some-file.odt
However, you can always start an instance yourself at the default port 2002 (or specify another port with -p/--port) and after use you can tear it down:
unoconv --listener & sleep 20 unoconv -f pdf *.odt unoconv -f doc *.odt unoconv -f html *.odt kill -15 %-
It is also possible to use a listener or LibreOffice instance that accepts connections on another system and use it from unoconv remotely. This way the conversion tasks are performed on a dedicated system instead of on the client system. This works only if you have a shared filesystem mounted at the same location.
Also beware that the pyuno python module needs to be compiled with the exact same version of python that you are using to load it. A lot of people that run into problems loading pyuno are actually using a precompiled LibreOffice that they downloaded somewhere and is incompatible with their python version. (Often the LibreOffice comes with its own python build that works flawlessly with their own pyuno)
The most recent unoconv works around this issue by automatically detecting incompatibilities, and restarting itself using a compatible python (the one that ships with LibreOffice).
You can influence the automatic detection by setting the UNO_PATH environment variable to point to an alternative LibreOffice installation, e.g.:
UNO_PATH=/opt/libreoffice3.5 unoconv some-file.odt
Since OpenOffice 2.3 you do not need an X display for starting ooffice. However you may need the openoffice.org-headless package from your distribution. Since LibreOffice 2.4 nothing special is needed, running in headless mode does not require X.
For any older OpenOffice releases, remember that ooffice requires an X display, even when using it in headless mode. One solution is to use Xvfb to create a headless X display for ooffice.
Some people have had difficulties using unoconv through webservices. Here is a list of probable causes:
-
X display issues (may require the headless subpackage)
-
Permission issues (unable to run or connect to LibreOffice or read/write)
-
SELinux issues (SELinux prevents you from connecting to LibreOffice)
If you encounter problems converting files, it often helps to try again. If you are using a listener, restarting the listener may help as well.
The reason for conversion failures are unclear, and they are not deterministic. unoconv is not the only project to have noticed problems with import and export filters using PyUNO. We assume these are related to internal state or timing issues that under certain conditions fail to correctly work.
We are looking into this with the LibreOffice developers to:
-
Collaborate closer to find, report and fix unexpected failures
-
Allow end-users to increase debugging and reporting to the project
If you encounter a problem with converting documents using unoconv, please consider that this could be to a number of things:
-
incomplete LibreOffice implementation
-
LibreOffice bug or regression specific to your version/distribution
-
LibreOffice import or export filter issue
-
problem related to stale lock files
-
problem related to the source document
-
problem related to permissions or SELinux
-
problem related to the python UNO bindings
-
problem related to the unoconv python script
It is recommended to follow any of these steps to pinpoint the problem:
-
if this is the first time you are using LibreOffice/OpenOffice, make sure you have all the required sub-packages installed, depending on the distribution this could be the xsltfilter, headless, writer, calc, impress or draw sub-packages.
-
check if there is no existing LibreOffice process running on the system that could interfere with proper functioning
# pgrep -l 'office|writer|calc'
-
check that there are no stale lock files present, e.g. '.~lock.file.pdf#' or '.~lock.index.html#'
-
check that the LibreOffice instance handling UNO requests is not handling multiple requests at the same time
-
try using the latest unoconv release, or the latest version on Github at: https://github.com/dagwieers/unoconv/downloads
-
try the conversion by opening the file in LibreOffice and exporting it through LibreOffice
-
try unoconv with a different minor or major LibreOffice version to test whether it is a regression in LibreOffice
-
try to load the UNO bindings in python manually
-
do this with the python executable that ships with the LibreOffice package/installer
# /opt/libreoffice3.5/program/python.bin -c 'import uno, unohelper'
-
or alternatively, run the disribution python (with the distribution LibreOffice)
# python -c 'import uno, unohelper'
-
If all of the above worked, the issue might still be related to import/export filters, LibreOffice or unoconv, so please report any information to reproduce the problem on the Github issue-tracker at: http://github.com/dagwieers/unoconv
And do mention that you already tried the above hints to troubleshoot the issue.
If you’re interested to help out with development, here are some pointers to interesting sources:
-
[Tutorial] Import uno module to a different Python install http://user.services.openoffice.org/en/forum/viewtopic.php?f=45&t=36370&p=166783
-
UDK: UNO Development Kit http://udk.openoffice.org/
-
Python-UNO bridge http://www.openoffice.org/udk/python/python-bridge.html
-
Python and OpenOffice.org http://wiki.services.openoffice.org/wiki/Python
-
OpenOffice.org developer manual http://api.openoffice.org/DevelopersGuide/DevelopersGuide.html
-
Framework/Article/Filter/FilterList OOo 2 1 http://wiki.services.openoffice.org/wiki/Framework/Article/Filter/FilterList_OOo_2_1
-
Framework/Article/Filter/FilterList OOo 3 0 http://wiki.services.openoffice.org/wiki/Framework/Article/Filter/FilterList_OOo_3_0
Other implementations using python and UNO:
Other tools that are useful or similar in operation:
-
Text based document generation: http://www.methods.co.nz/asciidoc/
-
DocBook to OpenDocument XSLT: http://open.comsultia.com/docbook2odf/
-
Simple (and stupid) converter from OpenDocument Text to plain text: http://stosberg.net/odt2txt/
-
Another python tool to aid in converting files using UNO: http://www.artofsolving.com/files/DocumentConverter.py http://www.artofsolving.com/opensource/pyodconverter