TL;DR
A long-standing memory leak in Ghostty was traced to a metadata mismatch when reusing large mmap allocations during scrollback pruning and has been fixed. The patch, which avoids reusing oversized pages and properly unmaps them, is merged into tip/nightly builds and will ship in the tagged 1.3 release in March.
What happened
Ghostty stores terminal content in a PageList, a doubly-linked list of memory "pages". Most pages use a standard fixed size pulled from a pool; occasionally Ghostty allocates larger, non-standard pages directly with mmap. To speed up scrollback trimming, the project reuses the oldest page as the newest without allocating new memory. A bug caused the code to reset a page's metadata to the standard size while leaving the underlying mmap allocation large. Later, when the page was freed, Ghostty assumed it was a pooled standard page and did not call munmap on the larger buffer, leaving that memory permanently allocated. The issue remained latent until CLI workloads (notably Claude Code) generated many non-standard pages, producing large memory footprints. The fix prevents reuse of non-standard pages: oversized pages are properly destroyed (munmap) and replaced with new standard pages from the pool. The change is merged and accompanied by tests and macOS VM tagging to aid future diagnostics.
Why it matters
- Affected processes could accumulate very large memory footprints (users reported up to 37 GB).
- The bug only triggered under specific conditions, making it hard to detect with existing tests.
- The patch eliminates the root cause by ensuring oversized mmap allocations are unmapped rather than treated as pooled memory.
- The fix is already merged and will be included in the 1.3 release, reducing risk for users of affected CLI workloads.
Key facts
- Ghostty uses a PageList (doubly-linked list) to store terminal content.
- Standard pages come from a memory pool; non-standard pages are allocated directly with mmap and must be munmap'd.
- A scrollback pruning optimization reused the oldest page to avoid allocations, updating metadata but not the mmap allocation.
- When metadata was reset to standard size for an actually large mmap allocation, munmap was never called and memory leaked.
- The leak existed since at least Ghostty 1.0 but was exposed at scale by workloads that produce many multi-codepoint graphemes (e.g., Claude Code).
- The fix avoids reusing non-standard pages: oversized pages are destroyed and a fresh standard page is allocated from the pool.
- A macOS virtual memory tagging mechanism was added to help identify and verify PageList allocations during debugging.
- The regression is covered by a new test to prevent recurrence; the change is merged into tip/nightly and slated for the tagged 1.3 release in March.
What to watch next
- The merged patch is available in tip/nightly builds and will appear in the tagged 1.3 release in March.
- Monitor user reports and memory telemetry after 1.3 to confirm the fix across diverse workloads.
- not confirmed in the source: whether Ghostty will adopt adaptive strategies (metrics-driven reuse) for non-standard pages in future releases.
Quick glossary
- PageList: A doubly-linked list data structure Ghostty uses to hold terminal content across discrete memory 'pages'.
- mmap: A system call that maps files or devices into memory; used here to allocate large, non-standard memory pages.
- munmap: The system call that releases memory previously allocated with mmap.
- Memory pool: A preallocated collection of fixed-size memory blocks reused to avoid frequent expensive allocations.
- Scrollback pruning: The process of trimming the oldest terminal history to respect a configured scrollback limit.
Reader FAQ
Has the memory leak been fixed?
Yes. The fix is merged, available in tip/nightly builds, and will be included in the tagged 1.3 release in March.
Was Claude Code responsible for the bug?
No. Claude Code's output exposed the bug by producing many non-standard pages, but it did not cause the defect.
How was the leak diagnosed?
The team added macOS VM tagging to PageList allocations and used a community reproduction to identify and verify the leak.
Will Ghostty change its reuse strategy for non-standard pages?
not confirmed in the source
MITCHELL HASHIMOTO Finding and Fixing Ghostty's Largest Memory Leak A few months ago, users started reporting that Ghostty was consuming absurd amounts of memory, with one user reporting 37 GB…
Sources
- Finding and fixing Ghostty's largest memory leak
- Memory leak: 37GB accumulated over 10 days via …
- 1.2.0 – Release Notes
- That's a shame to hear. I had to give up on Ghostty …
Related posts
- Code Is Clay: How AI’s Industrial Revolution Could Free Creative Coding
- Study: Overdose Deaths in America Are Falling After a ‘Supply Shock’
- Worst of Breed: A Satirical Catalog of Bad Software Practices