Title: Documents stay in memory until the cycle collector runs (part ↔ package reference cycle) · Issue #1646 · python-openxml/python-docx · GitHub
Open Graph Title: Documents stay in memory until the cycle collector runs (part ↔ package reference cycle) · Issue #1646 · python-openxml/python-docx
X Title: Documents stay in memory until the cycle collector runs (part ↔ package reference cycle) · Issue #1646 · python-openxml/python-docx
Description: A Document is never freed by reference counting. Its parts and its package refer to each other, so the document and all of its lxml trees stay in memory until Python's cycle collector runs. In a long-running process like a web worker or ...
Open Graph Description: A Document is never freed by reference counting. Its parts and its package refer to each other, so the document and all of its lxml trees stay in memory until Python's cycle collector runs. In a lo...
X Description: A Document is never freed by reference counting. Its parts and its package refer to each other, so the document and all of its lxml trees stay in memory until Python's cycle collector runs. In ...
Opengraph URL: https://github.com/python-openxml/python-docx/issues/1646
X: @github
Domain: github.com
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Documents stay in memory until the cycle collector runs (part ↔ package reference cycle)","articleBody":"A `Document` is never freed by reference counting. Its parts and its package refer to each other, so the document and all of its lxml trees stay in memory until Python's cycle collector runs. In a long-running process like a web worker or a batch job, that looks like a memory leak. I think it explains part of #1364 and #1428, since the trees do get freed by `gc.collect()`.\n\n#1428 also measured RSS after `gc.collect()`. On glibc, freed memory usually stays with the allocator until `malloc_trim(0)`, so the script below trims before each measurement.\n\n### Reproduce\n\n```python\nimport gc\nimport io\nimport sys\nimport weakref\n\nimport docx\n\n\ndef make_document():\n document = docx.Document()\n for i in range(3000):\n document.add_paragraph(f\"Paragraph {i}: \" + \"lorem ipsum dolor sit amet \" * 8)\n document.save(io.BytesIO())\n return document\n\n\n# The cycle: document part -> package -> package relationships -> document part\ndocument = make_document()\npart, package = document.part, document.part.package\nprint(\"part._package is package:\", part._package is package)\nprint(\"package.rels targets the part:\", any(r.target_part is part for r in package.rels.values()))\ndel document, part, package\n\n# Dropping the last reference does not free the document; only the cycle collector does\ngc.collect()\ngc.disable()\npackage_ref = weakref.ref(make_document().part.package)\nprint(\"package alive after its last reference was dropped:\", package_ref() is not None)\nprint(\"objects freed by gc.collect():\", gc.collect())\nprint(\"package alive after gc.collect():\", package_ref() is not None)\ngc.enable()\n\nif sys.platform == \"linux\": # how much memory those cycles hold (glibc)\n import ctypes\n\n libc = ctypes.CDLL(\"libc.so.6\")\n\n def rss_mib():\n libc.malloc_trim(0) # leave out freed memory that glibc can return\n with open(\"/proc/self/status\") as status:\n return next(int(line.split()[1]) for line in status if line.startswith(\"VmRSS:\")) / 1024\n\n gc.collect()\n gc.disable()\n print(f\"RSS baseline: {rss_mib():.0f} MiB\")\n for _ in range(10):\n make_document()\n print(f\"RSS after 10 documents, none referenced: {rss_mib():.0f} MiB\")\n gc.collect()\n print(f\"RSS after gc.collect(): {rss_mib():.0f} MiB\")\n gc.enable()\n```\n\nOutput with python-docx 1.2.0 and lxml 6.1.3 on CPython 3.14.10 (Linux, glibc 2.41):\n\n```\npart._package is package: True\npackage.rels targets the part: True\npackage alive after its last reference was dropped: True\nobjects freed by gc.collect(): 109\npackage alive after gc.collect(): False\nRSS baseline: 28 MiB\nRSS after 10 documents, none referenced: 106 MiB\nRSS after gc.collect(): 28 MiB\n```\n\nOn macOS with CPython 3.14.8 and 3.12.2, the first five lines match (3.12.2 frees 111 objects instead of 109). The RSS part only runs on Linux.\n\n### Why\n\n`Part.__init__` keeps `self._package = package`, and the package gets back to its parts through `OpcPackage.rels` → `_Relationship._target`. Parts also point at each other through `Part.rels`. So every part, along with the lxml tree it owns, is in a reference cycle. `master` has the same code.\n\nThe cycle collector is triggered by counts of tracked Python objects, not by memory use. A document leaves about 110 tracked objects behind, but its XML trees hold several MiB of native memory (about 8 MiB per document in the example above). Documents can pile up between collections, and a process that goes idle after building documents keeps them until some unrelated allocation triggers a collection.\n\n### Possible improvement\n\nAn opt-in way to release a document would help, for example a `Document.close()` (plus `__enter__`/`__exit__`) that breaks the part ↔ package references, so the XML trees are freed as soon as the caller is done with them. Weak back-references would remove the cycle entirely, but today a caller can hold on to a part without its `Document`, so that would change behavior.\n\nIn the meantime, a note in the docs saying that long-running processes should call `gc.collect()` after building or loading documents would save people from chasing an lxml leak.\n\nIf a `Document.close()` (or something like it) would be welcome, I can open a PR with tests.\n","author":{"url":"https://github.com/cleissonom","@type":"Person","name":"cleissonom"},"datePublished":"2026-11-13T17:44:37Z","url":"https://github.com/python-openxml/python-docx/issues/1646"}
| react-profiling | 0 |
| react-import-map | react,react-dom,react-dom/client,react-dom/profiling,react-is,react/compiler-runtime,react/jsx-dev-runtime,react/jsx-runtime,scheduler@b8488ee2c322 |
| route-pattern | /_view_fragments/issues/show/:user_id/:repository/:id/issue_layout(.:format) |
| route-controller | voltron_issues_fragments |
| route-action | issue_layout |
| fetch-nonce | v2:9b892c6c-133c-696c-c63d-f7ba795246d8 |
| current-catalog-service-hash | 81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114 |
| request-id | 8A28:177D5B:77C4D5:897E46:6AFF6391 |
| html-safe-nonce | 2e5e0f3e51d7a0a65b3cc6a91e646fc4f9aa63b58741402240b3761747ee0805 |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiI4QTI4OjE3N0Q1Qjo3N0M0RDU6ODk3RTQ2OjZBRkY2MzkxIiwidmlzaXRvcl9pZCI6IjIwNjM4NDUyMjYxOTkzNDQwMTciLCJyZWdpb25fZWRnZSI6ImlhZCIsInJlZ2lvbl9yZW5kZXIiOiJpYWQifQ== |
| visitor-hmac | de3229486f3b99420d30eaf371d76f33275635103c7b41984c83157182410495 |
| hovercard-subject-tag | issue:6376821139 |
| github-keyboard-shortcuts | repository,issues,copilot |
| google-site-verification | Apib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I |
| octolytics-url | https://collector.github.com/github/collect |
| analytics-location | / |
| fb:app_id | 1401488693436528 |
| apple-itunes-app | app-id=1477376905, app-argument=https://github.com/_view_fragments/issues/show/python-openxml/python-docx/1646/issue_layout |
| twitter:image | https://opengraph.githubassets.com/02330ab378df12d0dc0860993fdefb8b7ef88e29f1455884a02b43459c9e6418/python-openxml/python-docx/issues/1646 |
| twitter:card | summary_large_image |
| og:image | https://opengraph.githubassets.com/02330ab378df12d0dc0860993fdefb8b7ef88e29f1455884a02b43459c9e6418/python-openxml/python-docx/issues/1646 |
| og:image:alt | A Document is never freed by reference counting. Its parts and its package refer to each other, so the document and all of its lxml trees stay in memory until Python's cycle collector runs. In a lo... |
| og:image:width | 1200 |
| og:image:height | 600 |
| og:site_name | GitHub |
| og:type | object |
| og:author:username | cleissonom |
| hostname | github.com |
| expected-hostname | github.com |
| None | 41b58589a1c4eda1e3c8904144a412b88ca4455f63ca2ad3629f2e9f3c3a1d12 |
| turbo-cache-control | no-preview |
| go-import | github.com/python-openxml/python-docx git https://github.com/python-openxml/python-docx.git |
| octolytics-dimension-user_id | 3403760 |
| octolytics-dimension-user_login | python-openxml |
| octolytics-dimension-repository_id | 13592924 |
| octolytics-dimension-repository_nwo | python-openxml/python-docx |
| octolytics-dimension-repository_public | true |
| octolytics-dimension-repository_is_fork | false |
| octolytics-dimension-repository_network_root_id | 13592924 |
| octolytics-dimension-repository_network_root_nwo | python-openxml/python-docx |
| turbo-body-classes | logged-out env-production page-responsive |
| disable-turbo | false |
| browser-stats-url | https://api.github.com/_private/browser/stats |
| browser-errors-url | https://api.github.com/_private/browser/errors |
| release | 8968d6d6acc65d74e4df332d23932dd3fd0502a4 |
| ui-target | full |
| theme-color | #1e2327 |
| color-scheme | light dark |
| react-app-name | issues |
Links:
Viewport: width=device-width