René's URL Explorer Experiment


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

direct link

Domain: github.com


Hey, it has json ld scripts:
{"@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-profiling0
react-import-mapreact,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-controllervoltron_issues_fragments
route-actionissue_layout
fetch-noncev2:9b892c6c-133c-696c-c63d-f7ba795246d8
current-catalog-service-hash81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114
request-id8A28:177D5B:77C4D5:897E46:6AFF6391
html-safe-nonce2e5e0f3e51d7a0a65b3cc6a91e646fc4f9aa63b58741402240b3761747ee0805
visitor-payloadeyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiI4QTI4OjE3N0Q1Qjo3N0M0RDU6ODk3RTQ2OjZBRkY2MzkxIiwidmlzaXRvcl9pZCI6IjIwNjM4NDUyMjYxOTkzNDQwMTciLCJyZWdpb25fZWRnZSI6ImlhZCIsInJlZ2lvbl9yZW5kZXIiOiJpYWQifQ==
visitor-hmacde3229486f3b99420d30eaf371d76f33275635103c7b41984c83157182410495
hovercard-subject-tagissue:6376821139
github-keyboard-shortcutsrepository,issues,copilot
google-site-verificationApib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I
octolytics-urlhttps://collector.github.com/github/collect
analytics-location///voltron/issues_fragments/issue_layout
fb:app_id1401488693436528
apple-itunes-appapp-id=1477376905, app-argument=https://github.com/_view_fragments/issues/show/python-openxml/python-docx/1646/issue_layout
twitter:imagehttps://opengraph.githubassets.com/02330ab378df12d0dc0860993fdefb8b7ef88e29f1455884a02b43459c9e6418/python-openxml/python-docx/issues/1646
twitter:cardsummary_large_image
og:imagehttps://opengraph.githubassets.com/02330ab378df12d0dc0860993fdefb8b7ef88e29f1455884a02b43459c9e6418/python-openxml/python-docx/issues/1646
og:image:altA 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:width1200
og:image:height600
og:site_nameGitHub
og:typeobject
og:author:usernamecleissonom
hostnamegithub.com
expected-hostnamegithub.com
None41b58589a1c4eda1e3c8904144a412b88ca4455f63ca2ad3629f2e9f3c3a1d12
turbo-cache-controlno-preview
go-importgithub.com/python-openxml/python-docx git https://github.com/python-openxml/python-docx.git
octolytics-dimension-user_id3403760
octolytics-dimension-user_loginpython-openxml
octolytics-dimension-repository_id13592924
octolytics-dimension-repository_nwopython-openxml/python-docx
octolytics-dimension-repository_publictrue
octolytics-dimension-repository_is_forkfalse
octolytics-dimension-repository_network_root_id13592924
octolytics-dimension-repository_network_root_nwopython-openxml/python-docx
turbo-body-classeslogged-out env-production page-responsive
disable-turbofalse
browser-stats-urlhttps://api.github.com/_private/browser/stats
browser-errors-urlhttps://api.github.com/_private/browser/errors
release8968d6d6acc65d74e4df332d23932dd3fd0502a4
ui-targetfull
theme-color#1e2327
color-schemelight dark
react-app-nameissues

Links:

Skip to contenthttps://github.com/python-openxml/python-docx/issues/1646#start-of-content
https://github.com/
Sign inhttps://github.com/login?return_to=https%3A%2F%2Fgithub.com%2Fpython-openxml%2Fpython-docx%2Fissues%2F1646
GitHubRepository hosting, code review, and collaborationhttps://github.com/platform
CopilotAI coding agent for tasks, projects, and automated workhttps://github.com/features/copilot
ActionsCI/CD and automationhttps://github.com/features/actions
Code QualityQuality analysis, fixes, and enforcementhttps://github.com/features/code-quality
CodespacesCloud development environmentshttps://github.com/features/codespaces
Code SecurityVulnerability detection and remediationhttps://github.com/security/advanced-security/code-security
Secret ProtectionSecret scanning and leak preventionhttps://github.com/security/advanced-security/secret-protection
All Featureshttps://github.com/features
Documentationhttps://docs.github.com/en
Traininghttps://learn.github.com/skills
Certificationshttps://learn.github.com/credentials
Build with Copilothttps://github.com/features/ai
Customize Copilothttps://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/customize-copilot-overview
Integrationshttps://github.com/marketplace
Trending reposhttps://github.com/trending
GitHub Sponsorshttps://github.com/open-source/sponsors
Developer articleshttps://github.com/resources/articles
ChangelogYour source for the latest features, improvements, and fixes across GitHub products, all in one place.https://github.blog/changelog/
Enterpriseshttps://github.com/enterprise
Teamhttps://github.com/team
Startupshttps://github.com/enterprise/startups
Nonprofitshttps://github.com/solutions/industry/nonprofits
Healthcarehttps://github.com/solutions/industry/healthcare
Financial serviceshttps://github.com/solutions/industry/financial-services
Manufacturinghttps://github.com/solutions/industry/manufacturing
Governmenthttps://github.com/solutions/industry/government
See all industrieshttps://github.com/solutions/industry
Why GitHubhttps://github.com/why-github
Customer Storieshttps://github.com/customer-stories
Business insightshttps://github.com/solutions/executive-insights
Trust Centerhttps://github.com/trust-center
GitHub Advanced SecurityEnterprise-grade code securityhttps://github.com/security/advanced-security
Copilot for businessEnterprise-grade AI featureshttps://github.com/features/copilot/copilot-business
Premium SupportEnterprise-grade 24/7 supporthttps://github.com/enterprise/premium-support
Documentationhttps://docs.github.com/en
Resource centerhttps://github.com/resources
Bloghttps://github.blog/
Events & webinarshttps://github.com/resources/events
Community Forumhttps://github.com/orgs/community/discussions
Customer Storieshttps://github.com/customer-stories
Integrationshttps://github.com/marketplace
Customer supporthttps://help.github.com/
Traininghttps://learn.github.com/skills
GitHub Statushttps://www.githubstatus.com/
Abouthttps://github.com/about
Partnershttps://github.com/partners
Changeloghttps://github.blog/changelog/
GitHub UniverseThe event for developers, by developers — talks, workshops, and what’s next for GitHub.https://githubuniverse.com/
Pricinghttps://github.com/pricing
Sign inhttps://github.com/login?return_to=https%3A%2F%2Fgithub.com%2Fpython-openxml%2Fpython-docx%2Fissues%2F1646
Sign uphttps://github.com/signup?ref_cta=Sign+up&ref_loc=header+logged+out&ref_page=%2F%3Cuser-name%3E%2F%3Crepo-name%3E%2Fvoltron%2Fissues_fragments%2Fissue_layout&source=header-repo&source_repo=python-openxml%2Fpython-docx
Reloadhttps://github.com/python-openxml/python-docx/issues/1646
Reloadhttps://github.com/python-openxml/python-docx/issues/1646
Reloadhttps://github.com/python-openxml/python-docx/issues/1646
python-openxmlhttps://github.com/python-openxml
python-docxhttps://github.com/python-openxml/python-docx
Codehttps://github.com/python-openxml/python-docx
Issues387 (387)https://github.com/python-openxml/python-docx/issues
Pull requests167 (167)https://github.com/python-openxml/python-docx/pulls
Actionshttps://github.com/python-openxml/python-docx/actions
Projectshttps://github.com/python-openxml/python-docx/projects
Wikihttps://github.com/python-openxml/python-docx/wiki
Security and qualityhttps://github.com/python-openxml/python-docx/security
Insightshttps://github.com/python-openxml/python-docx/insights
https://github.com/python-openxml/python-docx
New issuehttps://github.com/login?return_to=https://github.com/python-openxml/python-docx/issues/1646
New issuehttps://github.com/login?return_to=https://github.com/python-openxml/python-docx/issues/1646
Documents stay in memory until the cycle collector runs (part ↔ package reference cycle)https://github.com/python-openxml/python-docx/issues/1646#top
https://github.com/cleissonom
cleissonomhttps://github.com/cleissonom
on Nov 13, 2026https://github.com/python-openxml/python-docx/issues/1646#issue-6376821139
#1364https://github.com/python-openxml/python-docx/issues/1364
#1428https://github.com/python-openxml/python-docx/issues/1428
#1428https://github.com/python-openxml/python-docx/issues/1428
Sign up for freehttps://github.com/signup?return_to=https://github.com/python-openxml/python-docx/issues/1646
Sign in to commenthttps://github.com/login?return_to=https://github.com/python-openxml/python-docx/issues/1646
https://github.com
Termshttps://docs.github.com/site-policy/github-terms/github-terms-of-service
Privacyhttps://docs.github.com/site-policy/privacy-policies/github-privacy-statement
Securityhttps://github.com/security
Statushttps://www.githubstatus.com/
Communityhttps://github.community/
Docshttps://docs.github.com/
Contacthttps://support.github.com?tags=dotcom-footer

Viewport: width=device-width


URLs of crawlers that visited me.