The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
The most reliable fully scripted pattern is to render a chart in Python, save it as a PNG or another supported image, and insert that file into a DOCX with python-docx. That produces a reproducible visual, but not an editable Word chart with an underlying data sheet. If readers must change values in Word, use Word’s embedded chart. If the document must follow a maintained workbook, use an Excel-linked chart and keep the workbook available for refresh.
Choose the chart workflow before writing code
“A chart in a Word document” can mean three different things. The choice determines how people edit data, how updates happen, and what must travel with the DOCX.
| Route | Data and editability | Update behavior | Best fit |
|---|---|---|---|
Python-rendered image inserted with python-docx |
The DOCX contains a picture. The cited API inserts an image; it does not describe an editable chart object with an associated workbook. | When source data changes, rerun the Python workflow to regenerate the image and document. This regeneration behavior is an implementation pattern, not an automatic refresh feature. | Scheduled or reproducible reports where the chart is a finished visual. |
| Word embedded chart | Chart data is stored in the Word file and can be edited through Word’s chart-data controls. | It does not update when the original Excel file changes. | A self-contained DOCX whose recipient should edit values in Word. |
| Excel-linked chart | The chart remains associated with an external workbook. | It can reflect workbook changes, but refresh requires access to the linked workbook and its expected location. | Documents maintained alongside a shared Excel source. |
Microsoft’s overview of these choices is available in Add a chart to your document in Word. Decide the route before designing the report template; otherwise, a polished image may later have to be replaced with a chart object, or a linked chart may fail for recipients who do not have the workbook.
Create a chart image in Python and insert it into a DOCX
This workflow separates two jobs: a Python plotting library creates pixels, and python-docx places those pixels on a page. The plotting library and visual style should follow your project’s requirements; the insertion API is the stable part of this pattern.
#1 Best Overall
1. Build the visualization from your project’s data
The following example uses a plotting library only to demonstrate the handoff. Replace the data preparation, chart type, colors, and typography with the conventions used by your project. Label the title, axes, and series so a reader can interpret the image after it is detached from the script.
from pathlib import Path
import matplotlib.pyplot as plt
# Replace these values with data produced by your pipeline.
months = ["Jan", "Feb", "Mar", "Apr"]
revenue = [120, 145, 138, 171]
output_dir = Path("build")
output_dir.mkdir(parents=True, exist_ok=True)
chart_path = output_dir / "quarterly-revenue.png"
fig, ax = plt.subplots(figsize=(7.0, 4.2))
ax.plot(months, revenue, marker="o", label="Revenue")
ax.set_title("Quarterly revenue")
ax.set_xlabel("Month")
ax.set_ylabel("Amount")
ax.legend()
ax.grid(axis="y", alpha=0.25)
fig.tight_layout()
fig.savefig(chart_path)
plt.close(fig)The important contract is chart_path: the chart must be saved to a known file or file-like object before insertion. Treat the saved artifact as a build output, not as an implicit side effect hidden inside document-generation code.
2. Create the document and insert the saved image
Document.add_picture() accepts a path or an IO stream. Set one physical dimension, such as inches or centimeters, so the chart fits the page. The quickstart examples and API reference show this image-insertion pattern in python-docx’s Quickstart and Document objects API.
Recommended Free Tools
from docx import Document
from docx.shared import Inches
report = Document()
report.add_heading("Monthly revenue", level=1)
report.add_paragraph("Revenue by month for the reporting period.")
# chart_path was created by the plotting step above.
report.add_picture(str(chart_path), width=Inches(6.2))
report.add_paragraph("Figure 1. Monthly revenue.")
report.save("build/revenue-report.docx")The resulting DOCX contains the rendered picture at the requested display width. It is not the same object as Word’s Insert > Chart feature: readers can resize or replace the picture, but they cannot open a Word chart data sheet for it.
3. Insert without creating a temporary image file
For a service that generates reports in memory, save the chart into a byte stream and pass that stream to add_picture. This keeps the same image-based behavior while avoiding a separate image file on disk.
from io import BytesIO
from docx import Document
from docx.shared import Inches
import matplotlib.pyplot as plt
buffer = BytesIO()
fig, ax = plt.subplots(figsize=(7.0, 4.2))
ax.bar(["North", "South", "West"], [42, 35, 51], label="Orders")
ax.set_title("Orders by region")
ax.set_ylabel("Orders")
ax.legend()
fig.tight_layout()
fig.savefig(buffer, format="png")
plt.close(fig)
buffer.seek(0)
doc = Document()
doc.add_heading("Regional orders", level=1)
doc.add_picture(buffer, width=Inches(6.2))
doc.save("build/regional-orders.docx")Reset the stream position before passing it to add_picture; otherwise the reader may be at the end of the stream and no image bytes will be available.
Control display size without distorting the chart
python-docx lets you specify an image width or height using physical units such as inches or centimeters. When only one dimension is supplied, it calculates the other proportionally, preserving the image’s aspect ratio. Supplying both dimensions can stretch or squash the image if they do not match the original ratio. The sizing behavior is documented in the Quickstart.
Native display size also depends on the image’s pixel dimensions and DPI metadata. The documentation states that an image without DPI information defaults to 72 DPI. That is a sizing rule, not a promise of print quality: inspect the generated DOCX in the Word environment used by your readers, especially when a chart contains small labels.
Choose a page-fitting width
- Use the document’s usable text width rather than the full physical page width; margins consume part of the page.
- Set a width in the insertion call and let the height follow the source ratio.
- Generate a wider source image when labels are crowded, then reduce its display width rather than forcing a narrow canvas during plotting.
- Check long titles, tick labels, legends, and data labels at the final Word size, not only in the plotting window.
Keep the source ratio when changing layout
If a template requires a different shape, change the plotting canvas and regenerate the image. Do not compensate by passing unrelated width and height values to Word. A changed canvas gives the plotting library room to reposition labels; arbitrary stretching changes the appearance of every mark and typeface.
Customize the visual before it enters Word
Python controls the chart’s data and rendering, while Word controls its placement in the document. Use the plotting stage for choices that affect interpretation:
- Chart form: match the form to the relationship you need to show. A line can show a sequence over time; bars can compare discrete categories. No single chart type is universally best.
- Titles and axes: state what is being measured and include units where they matter.
- Series and legends: give each series a meaningful name and remove a legend when direct labels make it unnecessary.
- Scale and ticks: use readable intervals and avoid a scale that hides the difference you want the reader to see.
- Labels: add values when exact numbers are important, but avoid overlapping labels on dense charts.
- Color and contrast: use a consistent palette across a report and ensure adjacent series remain distinguishable when printed or viewed in grayscale.
Microsoft identifies axes, data series, legends, titles, and labels as core chart elements in Present data in a chart. Those concepts apply to a rendered image as well: once the image is inserted, Word cannot independently edit those elements.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchAdd an editable chart directly in Word instead
Use Word’s chart workflow when the recipient needs to change the values, series, or chart type without rerunning Python. In current Microsoft 365 and Word 2016–2024 instructions, the desktop workflow is:
- Open the document and place the cursor where the chart should appear.
- Choose Insert > Chart.
- Select a chart category and a subtype, then choose OK.
- Replace the sample values in the data grid that opens with the values for your chart. Adjust the visible rows, columns, series names, and category labels to match the data.
- Close the data grid. Select the chart to use the chart controls for elements, styles, filters, layout, axes, titles, data labels, and legends.
The exact controls can vary by Word edition and platform. Microsoft’s chart guidance covers these editing controls and explains how chart elements are formatted.
An embedded chart stores its data in the Word document. That makes the DOCX self-contained for editing, but it also means later edits to an original Excel file do not flow into the embedded chart.
Use an Excel-linked chart when the workbook is the source of truth
A linked chart is appropriate when a Word report is maintained beside an Excel workbook and should reflect workbook changes. The link introduces a dependency that an image or embedded chart does not have.
- Create or open the chart in Excel and select it.
- Copy the chart.
- In Word, use the paste options that keep a link to the source workbook rather than embedding an independent copy. The wording of paste options can vary by Word version.
- Save the Word file and the workbook in locations that recipients or automated jobs can access consistently.
- When the workbook changes, open the Word document and allow the linked object to update or use Word’s available update command.
The Word document records where the external workbook is located. If a recipient lacks access, the file was renamed, or the path changed, the chart may not refresh and can show its last available values. Microsoft describes linked and embedded behavior in Add a chart to your document in Word and Present data in a chart.
Automate repeatable reports safely
For recurring reports, keep chart generation and document assembly as explicit stages. A predictable pipeline makes it clear which artifact must be regenerated when data changes.
- Load and validate the input data.
- Render each chart to a deterministic path or stream.
- Check that every expected image exists and contains the current reporting period.
- Open the DOCX template or create a new
Document. - Insert each image at a documented width, adding headings or captions as needed.
- Save the DOCX to a new output path.
- Open the output in the target Word environment and inspect page breaks, clipping, labels, and captions.
When the data changes, rerun the stages that produce the image and DOCX. Do not expect an inserted picture to discover changed source data by itself. If your operational requirement is “edit values in Word,” use an embedded chart instead; if it is “refresh from a workbook,” maintain the Excel link and its file-access contract.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Troubleshoot common failures
The document raises a file-not-found error
Confirm that the plotting step completed, that the path is the one passed to add_picture, and that the process’s working directory is what you expect. Prefer an explicit Path built from a known output directory instead of relying on a relative path whose meaning changes between a notebook, a scheduler, and a command-line run.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →The picture is missing when using a stream
Make sure the chart was saved to the stream in a supported format and call seek(0) before insertion. Keep the stream alive until add_picture has consumed it.
The chart looks stretched
Check whether both width and height were supplied with incompatible values. Pass only the desired width or only the desired height so the other dimension is calculated from the image ratio.
Labels are unreadable in Word
Inspect the chart at its final display size. Increase the source canvas, simplify crowded labels, shorten category names, or split one dense visualization into several focused charts. A larger source image does not by itself fix a poor layout, so check the rendered DOCX rather than judging only the source PNG.
The embedded chart did not change after editing Excel
That is expected for an embedded Word chart: its data lives in the document. Edit the chart’s data grid in Word, or replace it with an Excel-linked chart if workbook-driven updates are required.
Free tools Windows power users keep installed
One-click scans. No signup required.
The linked chart is stale or cannot refresh
Verify that the workbook still exists at the linked location and that the person or process opening the DOCX can read it. If the workbook was moved or renamed, repair the link or distribute the workbook through a stable shared location.
Quick Recap
A practical decision checklist
- Choose the Python image route when the report must be generated end to end by code and the chart can remain a finished visual.
- Choose an embedded Word chart when readers need to edit chart data inside the DOCX and the file should stand alone.
- Choose an Excel-linked chart when Excel is the maintained source and recipients can access the linked workbook.
- For Python images, save to a known path or stream, set one display dimension, and inspect the final DOCX.
- For Word charts, use the chart controls to adjust elements, styles, axes, titles, data labels, and legends.
- For linked charts, document the workbook location and test refresh using the same access conditions as your recipients.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
