python-docx-oss 0.3.2

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

[!WARNING] python-docx and python-docx-oss provide the same docx import namespace. Do not install both distributions in the same Python environment.

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

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, and its advanced OOXML capabilities before expanding document inspection, comparison, sanitization, 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.