python-docx-oss 0.4.0

A Python SDK for advanced creation and manipulation of Microsoft Word .docx files.

Overview

python-docx-oss is an independently evolving DOCX SDK built on the proven API foundation of python-docx. It keeps the familiar docx programming model while extending it for advanced OOXML and Open Packaging Convention (OPC) workflows.

Use it when an application needs more than basic paragraphs and tables: custom document metadata, application-owned XML, vector images, floating pictures, East Asian fonts, or low-level package and relationship access.

Capability Matrix

Installation

python -m pip install python-docx-oss

The distribution name is python-docx-oss, but the Python import namespace remains docx:

from docx import Document

python-docx-oss currently supports Python 3.12, 3.13, and 3.14.

Quick Start

Create a document entirely in memory:

from io import BytesIO

from docx import Document

document = Document()
document.add_heading("Quarterly Report", level=1)
document.add_paragraph("Generated entirely in memory.")

output = BytesIO()
document.save(output)

docx_bytes = output.getvalue()

The same APIs also accept filesystem paths:

document = Document("input.docx")
document.add_paragraph("Appended by python-docx-oss.")
document.save("output.docx")

Advanced Capabilities

Package inspection and fingerprints

Inspect damaged documents before opening them, without loading media payloads:

from docx import FingerprintPolicy, fingerprint, inspect

report = inspect("input.docx")
for finding in report.findings:
    print(finding.code, finding.partname)

digest = fingerprint("input.docx", policy=FingerprintPolicy(exclude_parts=("docProps/*",)))

These APIs leave inputs unchanged and restore seekable stream positions. Fingerprints ignore ZIP metadata and member ordering; all content is included unless explicitly excluded. See Package inspection and fingerprints for finding codes, XML comparison semantics, and policy rules.

Explicit repair and normalization

from docx import normalize, repair

repaired = repair(source_bytes, empty_custom_xml=True)
if repaired.report.succeeded:
    normalized = normalize(repaired.content, hyperlink_fields=True, hyperlink_runs=True)
    if normalized.report.succeeded:
        output_bytes = normalized.content

Operations are disabled by default. Results include committed changes, skipped cases, and errors; validation failures return the original bytes. See Repair and normalization for supported structures, selection callbacks, and preservation rules.

Custom properties

document = Document()
document.custom_properties["workflow_status"] = "approved"
document.custom_properties["revision"] = 3

Custom properties are visible in Microsoft Word and stored in /docProps/custom.xml. See Working with custom properties.

Custom XML

custom_xml = document.part.add_custom_xml_part(
    '<order xmlns="urn:example:orders" id="A-001"/>',
)
custom_xml.add_item("status", "ready")

See Working with Custom XML for lifecycle and compatibility considerations.

East Asian fonts

run = document.add_paragraph().add_run("English 与中文")
run.font.name = "Open Sans"
run.font.eastAsia = "Microsoft YaHei"

SVG and EMF streams can be passed to the standard picture APIs. Floating pictures are available through Document.add_float_picture() and Run.add_float_picture().

Compatibility and Scope

• The project maintains broad compatibility with the public python-docx API while following its own versioning and product roadmap.
• Clean lxml integration: Low-level OXML elements avoid shadowing lxml's Cython _Element.text descriptor (using .texts internally). This guarantees that standard element.itertext() on parent elements and untyped revision nodes (w:ins, w:del, w:txbxContent) never duplicates text, while high-level proxy APIs (paragraph.text, run.text) remain fully compatible with python-docx.
• Compatibility does not extend to every private or internal python-docx API. Test those integrations before migrating production systems.
• The SDK focuses exclusively on DOCX. It is not a general XLSX/PPTX Office suite.
• It edits document structure but does not implement Word's page-layout rendering engine.
• CLI, MCP, web, desktop, and Agent runtimes belong in separate packages that consume this SDK.

Documentation

• Documentation site
• Installation guide
• Quickstart
• User guide
• API reference
• Custom properties
• Custom XML
• python-docx compatibility
• Upstream maintenance
• Release history

Quality and Testing

The test suite combines unit and acceptance coverage with in-memory round-trip tests using documents created by Microsoft Word. The integration fixtures cover floating pictures, SVG fallback relationships, East Asian fonts, Custom XML parts, and core OPC package preservation.

For local development:

uv sync
uv run pytest
uv run ruff check .
uv run pyright

Project Status

The current focus is stabilizing the independent SDK baseline, its in-memory workflows, sanitization, and read-only package analysis before expanding document comparison, composition, and validation APIs.

Credits

This project builds on the original work of python-docx creator Steve Canny and its contributors. python-docx-oss is maintained by Ethan St Lee and its contributors.

Why “OSS”?

In Brazilian jiu-jitsu, “oss” is a greeting and an expression of respect. It reflects the same spirit of discipline and collaboration behind this project.

License

python-docx-oss is released under the MIT License.

Support

If this project is useful to you, you can support its continued development through the donation page.