「unoconv」による手軽なドキュメント変換
アプリケーションが引き続き unoconv に依存している場合は、まず Python/UNO 環境を確認し、内容を把握しているドキュメントを変換してください。このガイドでは、既存の Debian 12 ワーカー、DOCX のバッチ処理スクリプト、出力を受け入れる前に必要な PDF の確認手順を扱います。
unoconv は非推奨となり、リポジトリもアーカイブされています。新規実装には unoserver を使用してください。移行を計画する間、既存の unoconv ワークフローの保守にこの手順を活用してください。
「unoconv」の概要とオープンソースの機能
unoconv は、UNO バインディングを通じて LibreOffice を呼び出すオープンソースのコマンドラインツールです。インポートとエクスポートのフィルターは LibreOffice が提供するため、Python スクリプトをインストールするだけではドキュメントを変換できません。フォントも出力のレイアウトに影響します。
「unoconv」のセットアップとインストール
前提条件
環境がすでに構築され、バージョンが固定された専用のレガシーワーカーを使用してください。テストしたワーカーでは、Debian 12 Bookworm、ディストリビューションの Python 3.11.2、対応する python3-uno、Debian パッケージ 0.7-2 の unoconv 0.7、LibreOffice Writer 7.4.7.2、fonts-liberation2 の Liberation Sans を使用しました。これらはレガシー環境の保守用にテストしたバージョンです。新しいアプリケーションに古い構成をインストールすることを推奨するものではありません。
ワーカーには、書き込み可能な LibreOffice ユーザープロファイルと一時ディレクトリが必要です。同じプロファイルを使うデスクトップの LibreOffice セッションや共有リスナーがない状態で、バッチを一度に一つずつ実行してください。最初の変換には、内容が既知で信頼できる
DOCX と ODT ドキュメントを使用してください。ページ分割を評価する前に、実際のドキュメントで使うフォントをインストールしてください。以下の検査コマンドには、PDF を確認するマシン上に Poppler の
poppler-utils が必要です。ワーカー自体でも、同じ出力ファイルにアクセスできる別のマシンでも構いません。
Linux(Ubuntu/Debian)へのインストール
Debian の Bookworm パッケージ は、このレガシー版の
unoconv を提供しています。ディストリビューションの Python と UNO パッケージは組み合わせたまま維持してください。以下の確認では、仮想環境の外で
python3 が /usr/bin/python3 を参照することを前提としています。各コマンドを個別に検証し、変換前にこのインタープリターで UNO をインポートできるか確認します。
(
for tool in python3 unoconv libreoffice fc-match; do
command -v "$tool" >/dev/null || { printf 'Missing %s\n' "$tool" >&2; exit 1; }
done
python3 -c 'import uno, unohelper; print(uno.__file__)' &&
python3 --version &&
unoconv --version &&
libreoffice --version &&
fc-match -f '%{family}\n' 'Liberation Sans'
)
テストしたワーカーでは、UNO は /usr/lib/python3/dist-packages/uno.py から読み込まれました。インポートに失敗する場合や、表示されたバージョンがデプロイ環境の検証済みイメージと異なる場合は、作業を中止してください。これは既存のワーカーを確認する手順であり、現在の Ubuntu や Debian リリース向けのインストール手順ではありません。
出力を確認するマシンでは、PDF ツールも確認してください。ここでの確認には Poppler 26.08.0 を使用しました。
(
for tool in pdfinfo pdftotext pdftoppm; do
command -v "$tool" >/dev/null || { printf 'Missing %s\n' "$tool" >&2; exit 1; }
done
pdfinfo -v
)
macOS へのインストール
Homebrew では unoconv が無効化されています。LibreOffice だけをインストールしても、動作する unoconv/Python の組み合わせにはなりません。この手順では macOS へのインストールを検証していません。レガシーの macOS ワーカーから移行する際は、保守されている後継ツールのインストールガイドに従ってください。
Windows へのインストール
Windows ネイティブ環境と WSL へのインストールは、このガイドのテスト対象外です。WSL 自体は、対応する Python、UNO バインディング、フォント、LibreOffice フィルターを提供しません。未検証の環境の問題が WSL への切り替えで解決すると考えないでください。
DOCX から PDF へのドキュメント変換手順
作業ディレクトリ内の document.docx に内容が既知の DOCX ドキュメントを、notes.odt に内容が既知の ODT ドキュメントを配置してください。想定されるページ数、見出し、末尾の段落、表や図を記録してください。以下のコマンドは入力と同じ場所に document.pdf と
notes.pdf を書き込み、既存の PDF を置き換える可能性があるため、これらの出力先が存在しないディレクトリを使用してください。
unoconv -f pdf ./document.docx &&
unoconv -f pdf ./notes.odt
以下のコマンドで DOCX の変換結果を検査してください。document.txt と、document-page-1.png のような連番付き PNG ファイルが書き込まれます。確認を繰り返すと、これらの検査用ファイルは置き換えられます。
pdfinfo -box ./document.pdf &&
pdftotext -layout ./document.pdf ./document.txt &&
pdftoppm -cropbox -r 96 -png ./document.pdf ./document-page
各ページの最後の段落も含めて、ページ数と抽出したテキストを元の文書と比較してください。レンダリングされたすべての PNG を開き、表、図、余白、改ページを確認してください。CropBox のレンダリングでは表示領域が描画されるため、その外側にある内容によって切り抜きの問題が隠れることはありません。notes.pdf についても、notes.txt と
notes-page プレフィックスを使用して同じ検査を繰り返してください。空でないファイル、PDF シグネチャ、コマンドの成功だけでは、正しいドキュメントが欠けることなく変換された証拠にはなりません。
スクリプトによるドキュメント変換の自動化
動作確認済みの環境で DOCX を順次バッチ処理するには、以下を
convert_documents.py として保存してください。大文字と小文字を区別せず .docx サフィックスを持つ通常ファイルを選択し、ディレクトリとシンボリックリンクはスキップします。新規の出力ディレクトリが必要です。基本的なアーカイブ検査では、Transitional と Strict の両方の OOXML メインドキュメントの名前空間を認識しますが、完全な OOXML スキーマ検証ツールではありません。
import os
from pathlib import Path
import posixpath
import subprocess
import sys
from tempfile import TemporaryDirectory
from urllib.parse import unquote
from xml.etree import ElementTree
from zipfile import BadZipFile, ZipFile
import zlib
def check_docx(path):
relationship_types = {
'http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument',
'http://purl.oclc.org/ooxml/officeDocument/relationships/officeDocument',
}
document_tags = {
'{http://schemas.openxmlformats.org/wordprocessingml/2006/main}document',
'{http://purl.oclc.org/ooxml/wordprocessingml/main}document',
}
with ZipFile(path) as archive:
if archive.testzip() is not None:
raise ValueError('Damaged DOCX member')
relationships = ElementTree.fromstring(archive.read('_rels/.rels'))
main_parts = [item for item in relationships
if item.get('Type') in relationship_types
and item.get('TargetMode', 'Internal') == 'Internal']
if len(main_parts) != 1:
raise ValueError('Missing main document relationship')
part = posixpath.normpath(unquote(main_parts[0].get('Target', '')).lstrip('/'))
types = ElementTree.fromstring(archive.read('[Content_Types].xml'))
content_type = 'application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml'
if not any(item.get('PartName') == '/' + part
and item.get('ContentType') == content_type for item in types):
raise ValueError('Not a DOCX main part')
if ElementTree.fromstring(archive.read(part)).tag not in document_tags:
raise ValueError('Not a Word document')
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:
check_docx(path)
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, KeyError, BadZipFile, ElementTree.ParseError,
zlib.error, NotImplementedError, RuntimeError, 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')
DOCX ファイルを docs に配置し、new-pdfs ディレクトリが存在しない状態で実行してください。
python3 convert_documents.py docs new-pdfs
このスクリプトは失敗後も後続のファイルの処理を試み、いずれかのファイルが失敗するとステータス 1 を返します。失敗したファイル名を報告し、一時的な候補ファイルを削除して、拡張子を除く名前が衝突する場合も含めて既存の出力先を保持します。別のファイルが失敗しても、成功した PDF は利用可能なまま残ります。使用前に、上記のテキストとレンダリングの検査で確認してください。出力の確定は、コンバーターが正常に終了し、空でない候補ファイルを生成したことだけを意味します。
再試行する場合は、確定済みの PDF を保持し、別の新規出力ディレクトリを使用してください。選択対象が空の場合、出力ディレクトリを作成せずにステータス 1 を返します。120 秒のタイムアウトは各クライアントプロセスの実行時間を制限するもので、LibreOffice の処理停止を保証するものではありません。中断されたワーカーはステージングディレクトリを残すことがあるため、再試行前にそのワーカーが所有するストレージを確認してください。このスクリプトは信頼できるローカルバッチ用であり、信頼できないアップロードを受け付けるエンドポイント用ではありません。そのようなワーカーには、独自のプロセス監視、リソース制限、ファイルシステムの分離が必要です。
よくある問題のトラブルシューティング
Python バージョンの競合
UNO のインポート確認に失敗した場合は、どの Python が実行されているか、インストール済みの UNO ブリッジと一致するかを確認してください。開発元のドキュメントに、このインタープリター要件が記載されています。任意の仮想環境を用意するだけでは不十分です。標準の venv では、ディストリビューションの UNO モジュールが見えなくなります。Python のバージョンだけを変更しても、対応するブリッジはインストールされません。
LibreOffice バージョンの互換性
テストした Debian の unoconv は、Python 3.11 で
distutils の非推奨警告を出します。変換が成功しても、実際の PDF の確認が必要です。レガシーイメージでは、検証済みの
Python/UNO/LibreOffice の組み合わせを維持してください。ドキュメントの変換が失敗した場合は、同じドキュメントを LibreOffice で開いてエクスポートし、インポート/エクスポートの問題と unoconv クライアント経由の問題を切り分けてみてください。
コンテナへのデプロイ時の注意点
コンテナでは、変換を実行するユーザーが書き込めるプロファイル、キャッシュ、データ、ランタイム、一時ディレクトリを用意する必要があります。XDG_CONFIG_HOME、XDG_CACHE_HOME、XDG_DATA_HOME、XDG_RUNTIME_DIR を設定する場合は、LibreOffice を起動する前にディレクトリを作成してください。書き込み可能なプロファイルがないと、ドキュメント変換前に起動が停止することがあります。処理は逐次実行し、クライアントがタイムアウトしたら管理対象のワーカー全体を停止してください。クライアントだけを終了しても、後始末が完了した証拠にはなりません。
現在の代替手段と比較
| デプロイ環境 | 選択肢 |
|---|---|
| バージョン固定済みの既存レガシーワーカー | 代表的なドキュメントをテストしながら unoconv を保守 |
| 新規デプロイ | unoserver を使用 |
unoserver(推奨)
unoserver は、常駐する LibreOffice ワーカーと変換クライアントを分離します。サーバーには引き続き UNO をインポートできる Python インタープリターが必要であり、この依存関係がなくなるわけではありません。unoserver のインストール手順 に従い、保守されている連携方法については Rust からのドキュメント変換 を参照してください。このページのテスト対象は unoconv であり、この別のサーバーワークフローではありません。
LibreOffice CLI
単発の変換には、LibreOffice のコマンドラインエクスポートオプション も使用できます。テストした Debian ワーカーでは、以下のコマンドがカレントディレクトリに
document.pdf を書き込みます。
libreoffice --headless --convert-to pdf ./document.docx
存在しない出力先を使用し、同じ PDF 検査を実施してください。LibreOffice は既存の PDF を置き換えることがあり、終了ステータスだけでは出力内容を確認できません。この方法は unoconv クライアントを経由しませんが、引き続き LibreOffice のフィルターとフォントを使用します。
クラウドベースのソリューション
オフィス文書用ワーカーを運用する代わりに API 経由で利用したい場合は、代表的なドキュメントで Transloadit のドキュメント変換サービス を評価してください。これは別の連携方法であり、上記のローカルコマンドはホスト型サービスをテストするものではありません。
