“unoconv” para facilitar a conversão de documentos
Converter documentos entre formatos diferentes é uma tarefa comum para desenvolvedores e profissionais. Historicamente, o unoconv foi uma ferramenta de código aberto que usava o LibreOffice para converter documentos como DOCX, ODT e XLSX para PDF e outros formatos.
O unoconv está descontinuado e seu repositório foi arquivado. Para todas as novas implementações, use o unoserver, o sucessor moderno. Este post é mantido como referência histórica e para quem ainda dá suporte a fluxos de trabalho existentes com o unoconv.
Introdução ao “unoconv” e seus recursos de código aberto
O “unoconv” (Universal Office Converter) é um utilitário de linha de comando que usa o LibreOffice para converter documentos. Ele oferece suporte a uma ampla variedade de formatos de documento, o que o torna útil para desenvolvedores que mantêm sistemas legados ou dão suporte a fluxos de trabalho existentes. Embora o unoconv esteja descontinuado, ele continua sendo um exemplo didático de como automatizar tarefas de conversão de documentos.
Como configurar e instalar o “unoconv” no seu sistema
Pré-requisitos
Antes de usar o “unoconv”, verifique se o LibreOffice está instalado no seu sistema, já que o unoconv depende dele para realizar as conversões. Saiba que o unoconv pode ter problemas de compatibilidade com versões modernas do Python; considere migrar para o unoserver em novos projetos.
Instalação no Linux (Ubuntu/Debian)
Em uma implantação legada existente, verifique se a sua distribuição ainda empacota o unoconv:
apt-cache policy libreoffice unoconv
A disponibilidade do pacote não garante compatibilidade com as suas versões do Python e do LibreOffice. Mantenha os ambientes legados com versões fixadas e testados. Para uma nova implantação, siga as instruções de instalação do unoserver, que continua sendo mantido.
Instalação no macOS
A fórmula do unoconv no Homebrew está desativada porque o repositório do projeto foi arquivado. Não
use brew install unoconv em uma nova configuração. Instale o LibreOffice e siga as
instruções do unoserver para selecionar um interpretador Python capaz de importar o módulo
uno do LibreOffice:
brew install --cask libreoffice
Instalação no Windows
O suporte nativo do unoconv ao Windows é limitado. Recomendamos usar o Subsistema do Windows para Linux (WSL2) e seguir as instruções de instalação para Linux para garantir a compatibilidade.
Casos de uso e cenários comuns
Desenvolvedores podem usar o unoconv para diversas tarefas, incluindo:
- Conversões em lote: converta vários arquivos DOCX para PDF em uma única operação.
- Automação da geração de relatórios: gere relatórios em PDF automaticamente a partir de modelos de documento.
- Manutenção de sistemas legados: dê suporte e mantenha fluxos de trabalho que ainda dependem do unoconv.
- Processamento no lado do servidor: integre a conversão de documentos a aplicações de back-end para processamento automatizado.
Guia passo a passo: como converter documentos de DOCX para PDF
A conversão básica com o unoconv é simples. Para converter um único arquivo DOCX para PDF, execute:
unoconv -f pdf document.docx
Para um pequeno conjunto de arquivos em um diretório sem saídas PDF conflitantes:
unoconv -f pdf ./*.docx
Como automatizar tarefas de conversão de documentos com scripts
Automatizar a conversão de documentos pode otimizar seu fluxo de trabalho. O script Python a seguir
mostra como converter arquivos DOCX em uma instalação do unoconv que já esteja funcionando.
Salve-o como convert_documents.py e execute python3 convert_documents.py docs new-pdfs. Ele exige um
novo diretório de saída, ignora diretórios e links simbólicos e só publica cada resultado depois que
o comando é concluído com sucesso. Se alguma conversão falhar, o processo termina com status de
falha depois de tentar converter os demais arquivos.
import os
from pathlib import Path
import subprocess
import sys
from tempfile import TemporaryDirectory
def convert_documents(input_dir, output_dir):
source = Path(input_dir).resolve(strict=True)
files = sorted(path for path in source.iterdir()
if not path.is_symlink() and path.is_file()
and path.suffix.lower() == '.docx')
if not files:
print('No DOCX files found', file=sys.stderr)
return 1
output = Path(output_dir).absolute()
output.mkdir(mode=0o700)
failures = 0
for path in files:
try:
with TemporaryDirectory(prefix='.conversion-', dir=output) as temporary:
candidate = Path(temporary) / 'result.pdf'
subprocess.run(
['unoconv', '-f', 'pdf', '-o', str(candidate), str(path)],
check=True, timeout=120,
)
if not candidate.is_file() or candidate.stat().st_size == 0:
raise ValueError('No nonempty PDF was produced')
# Hard-link publication fails instead of replacing a destination that appeared.
os.link(candidate, output / (path.stem + '.pdf'))
print(f'Converted {path.name}')
except (OSError, ValueError, subprocess.SubprocessError):
failures += 1
print(f'Conversion failed: {path.name}', file=sys.stderr)
return 1 if failures else 0
if __name__ == '__main__':
if len(sys.argv) != 3:
sys.exit('Usage: python3 convert_documents.py <input-directory> <new-output-directory>')
try:
sys.exit(convert_documents(sys.argv[1], sys.argv[2]))
except (OSError, ValueError):
sys.exit('Cannot prepare conversion directories; use an existing input and a new output directory')
O tempo limite restringe o processo cliente, não necessariamente o trabalho que já está em execução no LibreOffice. Use um worker de conversão dedicado para arquivos não confiáveis, com limites de recursos do sistema operacional e sem acesso a partes sensíveis do sistema de arquivos. Confira a renderização, as fontes e a paginação em documentos representativos; um comando bem-sucedido não garante fidelidade visual.
Solução de problemas comuns
Conflitos de versão do Python
Sistemas modernos podem apresentar conflitos de versão do Python com o unoconv. Para resolver esses problemas, você pode:
- Usar um ambiente virtual Python com uma versão compatível.
- Instalar uma versão específica do Python que funcione bem com o unoconv.
- Migrar para o unoserver, que oferece melhor compatibilidade com o Python 3.
Compatibilidade de versão do LibreOffice
Verifique se a sua instalação do LibreOffice é compatível com o unoconv:
libreoffice --version
unoconv --version
Considerações sobre implantação em contêineres
Em ambientes conteinerizados, considere o seguinte:
- Faça o build a partir de uma distribuição com suporte e instale os pacotes do LibreOffice dela.
- Garanta que as fontes necessárias estejam instaladas.
- Configure as permissões de arquivo adequadas.
Essas medidas ajudam a evitar erros durante a conversão de documentos em implantações com contêineres.
Alternativas modernas e comparação
Unoserver (recomendado)
O unoserver é o sucessor do unoconv. Ele oferece um worker do LibreOffice de longa duração e um
cliente unoconvert separado. O interpretador Python usado por ele precisa
conseguir importar uno; um ambiente virtual qualquer não é suficiente.
Para uma integração completa, veja
conversão de documentos com Rust.
CLI do LibreOffice
O próprio LibreOffice oferece uma opção nativa de conversão pela linha de comando que dispensa o unoconv. Para converter um arquivo DOCX para PDF usando a CLI do LibreOffice, execute:
soffice --headless --convert-to pdf document.docx
Soluções baseadas em nuvem
Para ambientes de produção escaláveis, considere serviços de conversão de documentos baseados em nuvem ou soluções conteinerizadas que oferecem mais confiabilidade e manutenção sem esforço.
Conclusão
Embora o unoconv tenha servido bem aos desenvolvedores ao longo dos anos, sua descontinuação significa que novos projetos devem considerar alternativas modernas, como o unoserver ou serviços de conversão baseados em nuvem. Se você mantém sistemas legados, fique atento à compatibilidade e a possíveis problemas de versão do Python.
Se você procura uma solução robusta e escalável para conversão de documentos, considere conhecer o serviço de conversão de documentos da Transloadit.