conver — Word document converter

conver is a cross-platform Python package that converts Microsoft Word documents
using native system automation:

• macOS: JXA (JavaScript for Automation)
• Windows: PowerShell + Word COM automation

The package provides:

1. A high-level Python API: conver.conver()
2. A command-line interface: conver
3. A low-level IPC layer calling platform scripts
   (convert.jxa for macOS, convert.ps1 for Windows)

Conversion is performed via Microsoft Word itself, ensuring maximum compatibility with .docx, .doc, .rtf, .txt, .html, .odt.

• Cross-platform: macOS and Windows
• Uses the actual Microsoft Word engine
• Clean, minimal Python API
• CLI with direct input/output or format-selection flags
• Structured error handling via custom exceptions
• Filename-only outputs automatically placed next to the input file
• Safe low-level IPC layer between Python and native automation scripts

pip install --upgrade conver

If you primarily use conver as a command-line tool, it is best installed with pipx.
This isolates the package in its own virtual environment and avoids polluting your system Python:

pipx install --upgrade conver

After installation will be available globally:

conver --help

• Python 3.9+
• Microsoft Word must be installed on the system
• macOS (JXA) or Windows (PowerShell + Word COM automation)

from conver import conver

conver("document.docx", "document.pdf")

Returns: Path("/absolute/path/document.pdf")

conver("/Users/me/docs/a.docx", "a.pdf")

Automatically produces: /Users/me/docs/a.pdf

from conver import conver, UnsupportedFormat

try:
    conver("a.doc", "a.xyz")
except UnsupportedFormat:
    print("This output format is not supported.")

High-level document conversion API.

Signature:

conver(input_path, output_path, keep_open=False) -> pathlib.Path

Parameters:

• input_path: str | Path
  Path to the source document.
• output_path: str | Path
  Output filename or full path.
• keep_open: bool
  Leave Microsoft Word running after conversion.

Returns:

• pathlib.Path
  Absolute path of the generated output file.

Raises:

• InputFileNotFound
• UnsupportedFormat
• WordStartError
• SaveError
• IPCError
• PlatformNotSupported

The CLI supports two modes: direct output path, or format flags.

conver input.docx output.pdf

conver input.docx --pdf
conver input.docx --rtf
conver input.docx --txt
conver input.docx --html
conver input.docx --docx

If only one input file and no explicit output is given, the selected format determines the extension:

input.docx --pdf # -> input.pdf
input.docx --rtf # -> input.rtf

When OUTPUT is omitted, the resulting file is written next to the INPUT file. Examples:

conver a.docx --pdf # -> a.pdf
conver /path/x.docx # -> /path/x.pdf

When multiple inputs are provided, --output must be a directory.
If the directory does not exist, it will be created automatically.

If no format flag is provided and no explicit output path is given, the default output format is PDF:

conver input.docx # -> input.pdf

Usage:
    conver <input> <output>
    conver <input> [--pdf | --docx | --rtf | --txt | --html] [--keep-open]

Examples:
    conver a.docx a.pdf
    conver a.docx --pdf
    conver /path/to/file.doc --html

input
One or more input files. Patterns like *.docx are expanded by the shell.

output
Optional.
For single input: output filename.
For multiple inputs: must be a directory.

The CLI can process multiple input files at once:

conver *.docx -o outdir
conver file1.docx file2.docx file3.docx -o converted/

Rules:

• When multiple inputs are provided, --output must point to a directory.
• If the directory does not exist, it will be created automatically.
• If no format flag is provided, the default output format is PDF.
• Format flags (--pdf, --rtf, etc.) cannot be used together with --output FILE.
• Globbing (*.docx) is expanded by your shell before reaching the CLI.

If multiple input files are provided and --output is not specified, the CLI automatically attempts to infer a common parent directory for all inputs. If all files reside in the same directory, that directory becomes the output location.

Example:

conver *.docx
# -> writes output next to each input file

If the input files come from different directories, the output directory becomes ambiguous and the CLI will require an explicit --output.

Patterns like *.docx are expanded by your shell before the conver command is executed.

Examples:

conver *.docx -o outdir
conver path/*.rtf --pdf

This means the CLI receives the expanded list of files as separate arguments.

Format-selection flags: --pdf, --docx, --rtf, --txt, --html

Work only when OUTPUT is omitted, i.e.:

Allowed:

conver input.docx --pdf
conver input.docx output.pdf

Invalid:

conver input.docx output.pdf --pdf

Conversion capabilities depend on Microsoft Word.

Input formats: .docx, .doc, .pdf, .rtf, .odt, .txt, .html

Output formats: .pdf, .docx, .doc, .pdf, .rtf, .odt, .txt, .html

The script convert.jxa runs through:

osascript -l JavaScript

macOS may require granting Microsoft Word file-access permissions.

The script convert.ps1 uses:

Word.Application COM automation

If Word prompts the user, automation must be allowed.

These codes come from platform scripts and are mapped to exceptions by conver():

MIT License
(c) 2024 Timur Ulyahin
https://github.com/ucomru

GitHub:
https://github.com/ucomru/python-conver

PyPI:
https://pypi.org/project/conver/