The most reliable fully scripted method is to render your chart in Python, save it as a PNG or another supported image, and insert that file into a DOCX with python-docx. You can control the displayed width or height, and the other dimension is calculated proportionally. The result is a reproducible visual, not a Word chart with editable rows of data.
If readers must edit the data in Word, use Word’s native Insert > Chart workflow instead. If the document must follow a maintained Excel workbook, use a chart linked to that workbook. Those choices have different editing, updating and sharing consequences.
As an Amazon Associate I earn from qualifying purchases.
Choose the chart workflow before writing code
There are three practical routes. Select one based on where the source data should live and who needs to change it later.
| Route | Data and editability | What happens when data changes | Best fit |
|---|---|---|---|
Python-rendered image inserted with python-docx |
The DOCX contains a picture. The cited python-docx API does not create an editable Word chart or attach an underlying data sheet. |
Run the Python chart-and-document workflow again to replace the image. This is a workflow decision, not an automatic refresh feature. | Reproducible reports, scheduled documents and pipelines in which the chart is a finished visual. |
| Word embedded chart | Word stores chart data in the document, where it can be edited through Word’s chart data controls. | It does not update when the original Excel file later changes. | A self-contained DOCX whose recipient needs to edit values in Word. |
| Excel-linked chart | The chart remains associated with an external workbook. | It can reflect workbook changes, but refreshing depends on the linked workbook remaining accessible at its expected location. | Documents maintained alongside a controlled Excel source. |
Microsoft documents the embedded and linked behaviors in its Word chart instructions. The image-insertion route is documented in the python-docx quickstart and the Document API reference.
#1 Best Overall
Prerequisites and a predictable file layout
Install Python, python-docx, and whichever plotting package your project already uses. The plotting package is deliberately not prescribed here: the relevant API documentation establishes how to put an existing image in a DOCX, while chart construction and styling remain specific to your project.
Keep generated assets in a known location so a build can find them every time. A small project might use this layout:
report_project/
build_report.py
output/
assets/
Use a relative path based on the script or project root rather than a path that exists only on your workstation. For a temporary chart, add_picture can also read an in-memory file-like object; no permanent image file is required after the document has been saved.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Step-by-step: create a chart image and insert it into a DOCX
1. Prepare data and decide what the reader must see
Make the categories, values, units and time period explicit before choosing a visual. A comparison of categories generally needs one clearly named data series; a time sequence needs an ordered horizontal axis. Whatever library renders the chart, label axes and series so the image remains understandable after it is separated from the surrounding text.
2. Render and save the chart
The following complete example uses a plotting library only to demonstrate the image-producing part. Replace that block with your project’s chart code if you use another library.
from pathlib import Path
import matplotlib.pyplot as plt
from docx import Document
from docx.shared import Inches
ROOT = Path(__file__).resolve().parent
ASSETS = ROOT / "assets"
OUTPUT = ROOT / "output"
ASSETS.mkdir(exist_ok=True)
OUTPUT.mkdir(exist_ok=True)
chart_path = ASSETS / "monthly_sales.png"
docx_path = OUTPUT / "sales_report.docx"
months = ["Jan", "Feb", "Mar", "Apr", "May", "Jun"]
sales = [42, 55, 51, 68, 74, 81]
fig, ax = plt.subplots(figsize=(8, 4.5))
ax.plot(months, sales, marker="o", label="Sales")
ax.set_title("Monthly sales")
ax.set_xlabel("Month")
ax.set_ylabel("Units")
ax.legend()
fig.tight_layout()
fig.savefig(chart_path)
plt.close(fig)
document = Document()
document.add_heading("Sales report", level=1)
document.add_paragraph("Monthly sales for the first half of the year")
document.add_picture(str(chart_path), width=Inches(6.2))
document.add_paragraph("Figure 1. Monthly sales in units.")
document.save(docx_path)
Document() creates the Word document, and document.add_picture(...) inserts the saved image. The quickstart shows the same picture-insertion pattern and accepts a path or an IO stream. Setting width=Inches(6.2) establishes the displayed width; python-docx calculates the corresponding height to preserve the image’s aspect ratio.
3. Use a stream when the image is generated in memory
If your plotting code writes to a buffer instead of disk, pass that buffer directly:
Free tools Windows power users keep installed
One-click scans. No signup required.
from io import BytesIO
from docx import Document
from docx.shared import Inches
buffer = BytesIO()
fig.savefig(buffer, format="png")
buffer.seek(0)
document = Document()
document.add_picture(buffer, width=Inches(6.2))
document.save("output/report.docx")
Seek back to position zero before insertion. Otherwise the reader may receive an empty or incomplete stream because the file pointer is still at the end of the generated image.
4. Set only the dimension you actually know
You can specify a width or a height in physical units such as inches or centimeters. Supplying one dimension lets the library calculate the other proportionally. Supplying both can distort the chart when those values do not match the image’s aspect ratio. This is especially easy to do when a portrait chart is forced into a landscape-sized rectangle.
When no DPI property is present in the image, the documented native-size calculation uses a default of 72 DPI. That is a sizing behavior, not a promise of print quality. The final appearance also depends on the image’s pixel dimensions, its DPI metadata and the Word environment in which it is opened. Set a deliberate display width and inspect the resulting DOCX in the target Word edition.
5. Add context around the picture
Place a short descriptive paragraph before or after the image, and include units and the covered period in a caption. A reader should not have to infer whether “81” means units, dollars or a percentage. If the chart is part of a longer report, add a heading or bookmark that makes it easy to reference from the surrounding text.
Customize the Python-rendered chart before insertion
Most visual customization belongs in the plotting code, before add_picture runs. Match the chart type to the question rather than treating one type as universally best. Use a line for an ordered trend, bars for discrete category comparisons, and a scatter plot when the relationship between two numeric variables is the subject. These are practical choices, not a rule imposed by Word.
- Titles: State the measure and period, not just “Results.”
- Axes: Label both axes and include units. Use a consistent scale when readers compare multiple charts.
- Series: Give each series a descriptive name and use a legend only when it adds information.
- Labels: Add data labels when exact values matter and the chart remains legible at the planned DOCX width.
- Layout: Reserve enough space for long category names; otherwise labels can overlap or be clipped after insertion.
- Accessibility: Do not rely on color alone to distinguish series. Use distinct line styles, markers or direct labels, and provide a text explanation in the document.
Word’s own chart guidance identifies titles, axes, data series, legends, labels, styles, filters and layout as the principal chart elements. Those concepts are useful when you reproduce the same decisions in Python. The controls and names can vary by Word edition and platform; Microsoft’s instructions cover Microsoft 365 and Word 2016–2024, with some operations identified as Windows desktop steps.
Make the document reproducible when data changes
An inserted image is a snapshot. If the input values change, the DOCX will not discover that change by itself. Regenerate the chart, overwrite or version the image, and run the document-building script again. A deterministic pipeline should make the source data, chart filename and output filename explicit.
- Read the current data from the project’s approved source.
- Validate categories, units and missing values before plotting.
- Render the chart to a known path or an in-memory stream.
- Build a fresh DOCX and insert the new image at the intended width.
- Save the document to a new output path or replace the prior artifact according to your publishing process.
- Open the generated file in the target Word environment and check labels, page breaks, captions and image size.
Keep the data date or reporting period in the title or caption so an exported document can be understood after the source has moved on. If a report contains several figures, use stable, descriptive filenames and generate them in a controlled order.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallOutdated 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 matchUse Word’s embedded chart when the data must remain editable
For an editable chart, create it in Word rather than inserting a rendered picture. In a desktop copy of Word, choose Insert > Chart, select a chart type, and confirm. Word opens a data grid associated with the chart; replace the sample categories and values, then close or return to the document. You can later reopen the chart’s data controls to edit those values.
The data for this embedded chart is stored in the Word document. If an Excel workbook that supplied the original values is changed later, the embedded chart does not update from that workbook. This makes the DOCX self-contained, but it also means someone must edit the chart data in Word or recreate the chart when the source changes.
After inserting the chart, use Word’s chart controls to change elements, styles, filters, layout, axes, titles, data labels and legends. Select the chart to reveal the contextual controls, then apply the formatting that best communicates the measure. Exact menu names and placement differ between Word releases and operating systems, so verify the path in the edition used by your recipients.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Use an Excel-linked chart when the workbook is the source of truth
A linked chart is appropriate when a workbook is maintained separately and the Word document should be able to reflect its updates. Create or format the chart in Excel, copy it, and paste it into Word using the paste option that links the chart to the source workbook rather than embedding an independent copy. Microsoft’s chart instructions describe this linked-chart approach alongside embedded charts.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsThe link introduces a dependency: the DOCX points to the external workbook and a recipient must be able to access that file at the expected location for a refresh to work. Moving, renaming or restricting the workbook can leave the chart displaying its last saved values or prevent an update. Distribute the workbook through a stable, accessible location and test the complete handoff with the people who will open the document.
Use an embedded chart instead when recipients need a self-contained file, and use a Python-rendered image when the chart should be generated as part of a repeatable code pipeline without exposing editable chart data.
Troubleshoot common failures
The picture is missing or the script raises a file error
Confirm that the chart was saved before add_picture runs, that the path is correct, and that the process has permission to read the image and write the DOCX. Resolve paths from a known project directory instead of depending on the shell’s current directory. For a stream, verify that it is positioned at the beginning.
The chart looks stretched
Set only width or only height unless you have calculated matching dimensions for the image’s aspect ratio. Regenerate the source image with the intended proportions and insert it again.
The chart is too large, too small or unexpectedly paginated
Set an explicit display width in inches or centimeters and check the document’s margins and available text width. Native image size is influenced by pixel dimensions and DPI metadata; an image without DPI metadata uses the documented 72-DPI default for native sizing. A deliberate width is more predictable than relying on native size.
The chart is blurry in Word
Do not infer quality from the code alone. Inspect the generated image and the saved DOCX at the size readers will use. Pixel dimensions, DPI metadata, Word’s rendering and later zooming all affect the result; the available API documentation does not establish a universal DPI or resolution guarantee.
An Excel-linked chart will not refresh
Check that the linked workbook still exists at the location recorded by Word, that the recipient can access it, and that the document was not converted into an embedded or static picture during copying. If reliable offline sharing matters more than live updates, embed the chart or regenerate a Python image instead.
Quick Recap
A practical decision checklist
- Choose Python plus
python-docxwhen code should generate the entire report and the chart can be a finished visual. - Choose a Word embedded chart when recipients need to edit the values inside one self-contained DOCX.
- Choose an Excel-linked chart when Excel remains the maintained source and every recipient can reach that workbook.
- For any route, name units, periods, axes and series clearly, and test the final document on the Word platform your audience uses.
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.
