docxchart

Edit the data behind Word charts without disturbing the formatting.

Extract every chart's values from a .docx to JSON, edit the JSON, apply it back. Fills, label positions, axis settings and theme bindings are never touched.

Status: early. Handles same-length value edits on standard category charts. Anything it can't handle raises rather than guessing — see Limitations.

Install

pip install docxchart

Requires Python 3.11+.

CLI

docxchart list    report.docx
docxchart extract report.docx -o data.json
docxchart apply   report.docx --data data.json -o report-updated.docx

apply never writes in place. Omit -o and it errors.

Data format

{
  "_docxchart": {
    "source": "report.docx",
    "basedOn": "sha256:1f3a…",
    "extractedAt": "2026-07-29T09:14:22Z",
    "formatVersion": "1.0"
  },
  "charts": [
    {
      "key": "revenue_by_quarter",
      "_meta": {
        "title": "Revenue by Quarter",
        "type": "barChart",
        "keyStable": true,
        "readOnly": true
      },
      "series": [
        { "name": "2024", "formatCode": "#,##0" },
        { "name": "2025", "formatCode": "#,##0" }
      ],
      "rows": [
        { "category": "Q1", "2024": 120,  "2025": 130 },
        { "category": "Q2", "2024": null, "2025": 110 },
        { "category": "Q3", "2024": 95,   "2025": 99  }
      ]
    }
  ]
}

null is a genuine blank in the chart, rendered as a gap. It is not zero. Omitting a key means the same thing.

Dates are stored as Excel serial numbers with a formatCode, and are passed through unconverted.

Python API

from docxchart import ChartDoc

doc = ChartDoc.open("report.docx")

list(doc.charts)
# ['revenue_by_quarter', 'headcount']

chart = doc.charts["revenue_by_quarter"]
chart.table
# ChartTable(
#     categories=['Q1', 'Q2', 'Q3'],
#     series=[Series(name='2024', values=[120, None, 95])],
# )

chart.table.series[0].values = [130, 110, 99]

doc.validate()               # -> list[Finding]
doc.save("report-updated.docx")

ChartTable and Series are plain dataclasses. No XML is exposed.

Naming

Charts are identified by their Alt Text, which survives Word re-saves, insertions and deletions — unlike file paths and relationship IDs.

1. Right-click the chart → Edit Alt Text
2. Enter a key, e.g. revenue_by_quarter

Without Alt Text, the key falls back to the chart's title, slugified. This works, but the key changes if anyone edits the title. list marks these as unstable. Duplicate titles are suffixed by document order: revenue, revenue-2.

Limitations

Unsupported cases raise UnsupportedChart or UnsupportedEdit with a reason. Nothing is written on a partial or best-guess basis.

Not supported:

• Adding or removing categories — values can be changed, not the number of them
• Adding or removing series
• Scatter and bubble charts
• chartEx types: waterfall, treemap, sunburst, funnel, histogram, box & whisker, map
• Multi-level category axes
• Charts in headers, footers or footnotes
• Charts bound to an external data source
• Any change to appearance — colours, fonts, chart type, axis config and layout are read-only

Charts must be created in Word. docxchart only rebinds data on charts that already exist.

Notes

Word renders from the chart's cached values, not from the embedded workbook, but the workbook is what you see when you click Edit Data. docxchart always writes both, so the two never disagree.

Parts of the package that weren't changed come out byte-identical.

License

MIT — see LICENSE.