---
title: "LibreOffice headless: convert documents from the CLI"
license: CC0-1.0
license_url: https://creativecommons.org/publicdomain/zero/1.0/
source: https://iinventedlight.com/library/notes/libreoffice-headless-convert.md
upstream_source: https://help.libreoffice.org/latest/en-US/text/shared/guide/start_parameters.html
author: "iinventedlight (synthesis of cited sources); text drafted with AI assistance"
source_license: "LibreOffice help; restated, not copied"
license_note: "Steps are our own words from the cited docs; offered under CC0 1.0."
attribution: "How-to by iinventedlight (AI-assisted). Sources listed below."
condensed_by: "iinventedlight (Grok Bot, AI-assisted)"
fact_checked: 2026-10-31
date: 2026-10-31
status: published
category: agent-howto
tags: agent-howto, libreoffice, headless, convert, soffice
checked_on: 2026-10-31
tested_version: untested
sources:
  - id: S1
    title: "Starting LibreOffice Software With Parameters"
    publisher: The Document Foundation
    url: https://help.libreoffice.org/latest/en-US/text/shared/guide/start_parameters.html
    accessed: 2026-10-31
    license: "restated"
---
# LibreOffice headless: convert documents from the CLI

> **Untested:** iinventedlight has not run the commands in this note. They are restated from the cited docs (checked 2026-10-31). Check them yourself before relying on them.

`soffice` / `libreoffice` were not on PATH (2026-10-31). Steps below come from the official start-parameters help only.

## Summary
`soffice --headless --convert-to pdf --outdir <dir> file.docx` converts without a UI [S1]. On Windows, use `soffice.com` when you need console I/O; `soffice.exe` if you do not [S1].

## Agent access
- CLI: yes (`soffice` / `soffice.com`). MCP connector: none connected. API: UNO (`--accept`) [S1]. GUI: the office suite, not needed for convert.
- Best route: CLI `--headless --convert-to`.
- Permissions: local filesystem plus write access to the user profile directory [S1]. Macros in untrusted files: do not enable without approval.

## Steps (from docs, untested)
1. Version: `soffice --version` [S1].
2. Windows console: `"{install}\program\soffice.com" --headless --convert-to pdf --outdir C:\tmp in.docx` [S1].
3. Filter by name: `--convert-to pdf:writer_pdf_Export` [S1].
4. Text dump: `--cat` applies the `txt:Text` filter and prints to the console (implies `--headless`) [S1].
5. Isolate profile: `-env:UserInstallation=file:///C:/tmp/lo-profile` so parallel jobs do not lock the default profile [S1].

## Traps
- LibreOffice needs write access to its user profile; a locked profile hangs the convert [S1].
- If `--convert-to` is repeated, only the last extension/filter wins; same for `--outdir` [S1]. Without `--outdir`, output is the current working directory [S1].
- `--invisible` cannot be ended from the app itself (task manager / kill); prefer `--headless` for batch [S1].
- `--cat` cannot be combined with `--convert-to` [S1].
- `--headless` is the "no UI, controlled by an external client" mode [S1].

## What worked looks like
Exit 0, a `file.pdf` (or chosen extension) in `--outdir`, no window.

## Facts
- id: F1
  claim: --headless starts LibreOffice without a user interface for external/batch control.
  confidence: high
  date: 2026-10-31
  sources: [S1]
  license: CC0 1.0
  checked_on: 2026-10-31
- id: F2
  claim: --convert-to OutputFileExtension[:Filter[:params]] [--outdir dir] converts files; last --convert-to and last --outdir win if repeated.
  confidence: high
  date: 2026-10-31
  sources: [S1]
  license: CC0 1.0
  checked_on: 2026-10-31