Skip to main content

python-docx-oss

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

PyPI Python versions Code style: Ruff License: MIT

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, package inspection, configurable fingerprints, repair, or low-level package and relationship access.

Capability Matrix

Capability Status Primary API
Documents, paragraphs, tables, styles, sections, headers, and footers Stable Document() and document object APIs
Custom document properties Stable document.custom_properties
Custom XML lifecycle Stable add_custom_xml_part(), delete_custom_xml_part()
SVG and EMF images Stable add_picture()
Inline and floating pictures Stable add_picture(), add_float_picture()
Latin and East Asian font controls Stable run.font.name, run.font.hAnsi, run.font.eastAsia
Low-level OPC parts and relationships Stable document.part.package, part.rels
In-memory read, export, and independent copies Stable Document(), to_bytes(), copy()
Document sanitization Stable document.sanitize()
Read-only package inspection and streaming feature scanning Stable inspect(), ScanEvent
Configurable package-content fingerprints Stable fingerprint(), FingerprintPolicy, serialize_xml
Explicit empty Custom XML repair and hyperlink normalization Stable repair(), normalize()
Package and semantic diff Planned —

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, and compute reproducible content fingerprints 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 without loading media payloads. inspect() supports structural inventory, damage detection, and streaming story XML queries with caller-defined predicates. fingerprint() normalizes structural indentation (C14N 2.0 / fingerprint v3) and supports selective exclusions. See Package inspection and fingerprints for finding codes, streaming queries, 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 and transactional: validation failures return the original bytes. Hyperlink normalization converts field codes into native w:hyperlink elements while preserving text box boundaries and proofing markers. 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

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 behave
uv run ruff check tests/integration tests/fixtures/customxml/generate_fixture.py
uv run pyright tests/integration tests/fixtures/customxml/generate_fixture.py

Project Status

With version 0.5.0, the independent SDK baseline, in-memory workflows, package sanitization, streaming inspection, content fingerprinting (v3), and explicit package repairs are stabilized. Upcoming milestones focus on package and semantic diffing, composition, and schema-guided validation.

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.

Metadata

Release files for python-docx-oss 0.5.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for python-docx-oss 0.5.1
File Size Uploaded Provenance Actions
python_docx_oss-0.5.1.tar.gz 8.9 MB With provenance Details for python_docx_oss-0.5.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for python-docx-oss 0.5.1
File Interpreter ABI Platform Actions
python_docx_oss-0.5.1-py3-none-any.whl Python 3 none any Details for python_docx_oss-0.5.1-py3-none-any.whl

Total release size: 9.2 MB

Release files / python_docx_oss-0.5.1.tar.gz

Download URL python_docx_oss-0.5.1.tar.gz
Size 8.9 MB
Tags Source
SHA-256 checksum
How to use checksums
526bfa3f98bba747585c6c51f45fb64f2622f455bfe35b8fff04f0713ab92774
BLAKE2b-256 checksum
How to use checksums
a0719b66a5de1e49757dc18af6db6fcc262160a0bbbd64357bf26ae6814b32f5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.12.9

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.

Transparency log

Release files / python_docx_oss-0.5.1-py3-none-any.whl

Download URL python_docx_oss-0.5.1-py3-none-any.whl
Size 300.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c6bf504b834d52f85f2da57617a6f6bd19088265986ee7823d0b7068b5fd49e1
BLAKE2b-256 checksum
How to use checksums
83e0d764fdc3725999e2cc253bf26b554538cc0c8a530e1d9e36ee20a4999823
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.12.9

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.

Transparency log

Security for python-docx-oss 0.5.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for python_docx_oss-0.5.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.5.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page