{"id":689,"library":"python-docx","title":"python-docx (Microsoft Word .docx files)","description":"python-docx is a Python library for creating, reading, and updating Microsoft Word 2007+ (.docx) files. It provides an object-oriented API to interact with the structure and content of Word documents. The library is actively maintained, with regular releases addressing features and bug fixes.","status":"active","version":"1.2.0","language":"en","source_language":"en","source_url":"https://github.com/python-openxml/python-docx","tags":["office","word","document generation","docx","microsoft word"],"install":[{"cmd":"pip install python-docx","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Required for XML parsing and manipulation of .docx files. pip automatically handles this dependency.","package":"lxml","optional":false}],"imports":[{"note":"The primary class to interact with Word documents is 'Document', imported from the top-level 'docx' package. Avoid 'import docx' directly without further specifying the class, as it's not the primary entry point for document objects. Also, do not name your script 'docx.py' to avoid circular import errors.","wrong":"import docx","symbol":"Document","correct":"from docx import Document"},{"note":"When specifying measurements for elements like images, use units from `docx.shared` (e.g., `Inches`, `Cm`) to ensure correct scaling. Providing raw integer values will result in extremely small dimensions.","wrong":"width=2","symbol":"Inches","correct":"from docx.shared import Inches"}],"quickstart":{"code":"from docx import Document\nfrom docx.shared import Inches\n\ndocument = Document() # Create a new, blank Word document\ndocument.add_heading('Document Title', 0)\n\np = document.add_paragraph('A plain paragraph having some ')\np.add_run('bold').bold = True\np.add_run(' and some ')\np.add_run('italic.').italic = True\n\ndocument.add_heading('Heading, level 1', level=1)\ndocument.add_paragraph('Intense quote', style='Intense Quote')\n\ndocument.add_picture('image.png', width=Inches(1.25)) # Add an image (ensure 'image.png' exists)\n\ntable = document.add_table(rows=1, cols=3)\nhdr_cells = table.rows[0].cells\nhdr_cells[0].text = 'Qty'\nhdr_cells[1].text = 'Item'\nhdr_cells[2].text = 'Description'\n\ndocument.add_page_break()\n\ndocument.save('demo.docx')\nprint(\"Document 'demo.docx' created successfully.\")","lang":"python","description":"This quickstart demonstrates how to create a new Word document, add a title, paragraphs with styled text (bold, italic), insert an image, create a simple table, and add a page break. It saves the resulting document as 'demo.docx'. Ensure you have an 'image.png' file or remove the `add_picture` line to run without error."},"warnings":[{"fix":"Upgrade to Python 3.7 or a newer compatible version.","message":"Python 2 support was removed starting with version 1.0.0. The library now requires Python 3.7 or newer. Attempts to use it with Python 2 will result in errors.","severity":"breaking","affected_versions":"1.0.0 and above"},{"fix":"Always use `pip install python-docx` to get the correct and actively maintained library.","message":"The PyPI package name for this actively maintained library is `python-docx`, while an older, unmaintained package exists under the name `docx` (version 0.2.4, last updated 2009). This entry is for the actively developed `python-docx` as indicated by the provided GitHub URL. Installing `pip install docx` will give you the old, abandoned library.","severity":"gotcha","affected_versions":"All versions of `python-docx`"},{"fix":"Rename your script file to something other than `docx.py` (e.g., `my_document_script.py`).","message":"Naming your Python script file `docx.py` can cause a `ModuleNotFoundError` or `AttributeError` due to a circular import conflict with the `docx` module itself. The interpreter tries to import from your script instead of the installed library.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For complex template-based document generation or modifications, consider generating tables and content programmatically rather than attempting direct in-place modification of highly structured template elements. Inspect the generated XML if issues persist.","message":"When modifying existing documents, especially those with complex layouts, merged cells in tables, or specific styles, preserving original formatting can be challenging. Directly copying and modifying elements with `python-docx` might lead to unexpected formatting changes or document corruption if not handled carefully.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-05-12T17:50:43.772Z","next_check":"2026-07-13T00:00:00.000Z","problems":[],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":"1.2.0","install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.17,"mem_mb":6.7,"disk_size":"32.7M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.17,"mem_mb":6.7,"disk_size":"32.8M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":2.3,"import_time_s":0.11,"mem_mb":6.7,"disk_size":"33M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.12,"mem_mb":6.7,"disk_size":"33M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.25,"mem_mb":7.3,"disk_size":"34.7M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.28,"mem_mb":7.3,"disk_size":"34.9M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":2.3,"import_time_s":0.23,"mem_mb":7.3,"disk_size":"35M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.22,"mem_mb":7.3,"disk_size":"35M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.21,"mem_mb":7.2,"disk_size":"26.7M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.22,"mem_mb":7.2,"disk_size":"26.8M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":2.1,"import_time_s":0.2,"mem_mb":7.2,"disk_size":"27M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.2,"mem_mb":7.2,"disk_size":"27M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.19,"mem_mb":7.1,"disk_size":"26.4M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.22,"mem_mb":7.1,"disk_size":"26.5M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":2.2,"import_time_s":0.19,"mem_mb":7.1,"disk_size":"27M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.19,"mem_mb":7.1,"disk_size":"27M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.15,"mem_mb":6.5,"disk_size":"32.2M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.15,"mem_mb":6.5,"disk_size":"32.3M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":2.6,"import_time_s":0.15,"mem_mb":6.5,"disk_size":"33M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.13,"mem_mb":6.5,"disk_size":"33M"}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}