CJK characters not rendering properly

[birkhofflee]

Hey, today I was experimenting with a couple of new fonts until I noticed that the CJK characters are not rendering properly in Ghostty. I deleted the config to use the default settings, still it doesn't render in the correct way. It relates to #3499

Version 1.2.3
Build 12214
Commit 6d2dd585a

[danielwe]

Unfortunately I can't reproduce this. The screenshot below shows how it looks like for me with Ghostty 1.2.3 and a blank config. However, I don't have any CJK fonts installed other than the ones that come with the system. Since this looks like a font loading issue, I may need to install some the same fonts as you to be able to reproduce. Can you give me a list of (some of) the CJK fonts you have installed?

[birkhofflee]

Hi, thanks for looking into it. I searched for the fonts that support CJK in the Font Book app on my macOS, there were 243 of them. Do you want the full list of it?

The ones below have CJK in their names.

Output of ghostty +list-fonts:

Andale Mono
  Andale Mono

BIZ UDGothic
  BIZ UDGothic
  BIZ UDGothic Bold

BIZ UDMincho
  BIZ UDMincho

Berkeley Mono
  Berkeley Mono Bold
  Berkeley Mono Bold Oblique
  Berkeley Mono Oblique
  Berkeley Mono Regular

CommitMono Nerd Font
  CommitMono Nerd Font
  CommitMono Nerd Font Bold
  CommitMono Nerd Font Bold Italic
  CommitMono Nerd Font Italic

Courier New
  Courier New
  Courier New Bold
  Courier New Bold Italic
  Courier New Italic

Lantinghei TC
  Lantinghei TC Demibold
  Lantinghei TC Extralight
  Lantinghei TC Heavy

Menlo
  Menlo Bold
  Menlo Bold Italic
  Menlo Italic
  Menlo Regular

Monaco
  Monaco

Monaspace Argon Var
  Monaspace Argon Var ExtraLight Bold
  Monaspace Argon Var ExtraLight Bold Italic
  Monaspace Argon Var ExtraLight ExtraBold
  Monaspace Argon Var ExtraLight ExtraBold Italic
  Monaspace Argon Var ExtraLight ExtraLight Italic
  Monaspace Argon Var ExtraLight Italic
  Monaspace Argon Var ExtraLight Light
  Monaspace Argon Var ExtraLight Light Italic
  ...

Monaspace Krypton Var
  Monaspace Krypton Var ExtraLight Bold
  Monaspace Krypton Var ExtraLight Bold Italic
  Monaspace Krypton Var ExtraLight ExtraBold
  Monaspace Krypton Var ExtraLight ExtraBold Italic
  Monaspace Krypton Var ExtraLight ExtraLight Italic
  Monaspace Krypton Var ExtraLight Italic
  Monaspace Krypton Var ExtraLight Light
  ...

Monaspace Neon Var
  Monaspace Neon Var ExtraLight Bold
  Monaspace Neon Var ExtraLight Bold Italic
  Monaspace Neon Var ExtraLight ExtraBold
  Monaspace Neon Var ExtraLight ExtraBold Italic
  Monaspace Neon Var ExtraLight ExtraLight Italic
  Monaspace Neon Var ExtraLight Italic
  Monaspace Neon Var ExtraLight Light
  ...

Monaspace Radon Var
  Monaspace Radon Var ExtraLight Bold
  Monaspace Radon Var ExtraLight Bold Italic
  Monaspace Radon Var ExtraLight ExtraBold
  Monaspace Radon Var ExtraLight ExtraBold Italic
  Monaspace Radon Var ExtraLight ExtraLight Italic
  ...

Monaspace Xenon Var
  Monaspace Xenon Var ExtraLight Bold
  Monaspace Xenon Var ExtraLight Bold Italic
  Monaspace Xenon Var ExtraLight ExtraBold
  ...

Osaka
  Osaka-Mono

PCMyungjo
  PCMyungjo Regular

PT Mono
  PT Mono
  PT Mono Bold

SF Mono
  SF Mono Bold
  SF Mono Bold Italic
  SF Mono Heavy
  SF Mono Heavy Italic
  SF Mono Light
  SF Mono Light Italic
  SF Mono Medium
  SF Mono Medium Italic
  SF Mono Regular
  SF Mono Regular Italic
  SF Mono Semibold
  SF Mono Semibold Italic

I'm on macOS Sequoia 15.6.1. The language and region settings are in below if it's useful:

Let me know what else do you need from me to help you reproduce the issue.

[birkhofflee]

Ok right now it works again, I didn't do anything though - it should be a bug that rarely happens on a certain condition.

[danielwe]

Good to see! Did you restart Ghostty? Some font-related settings need a restart to take proper effect, and I wouldn't be too surprised if updating the config several times without restarting Ghostty could cause for a strange mix of typefaces like you showed in the OP.

[birkhofflee]

Good to see! Did you restart Ghostty? Some font-related settings need a restart to take proper effect, and I wouldn't be too surprised if updating the config several times without restarting Ghostty could cause for a strange mix of typefaces like you showed in the OP.

Maybe I did, but at most I just updated the font family settings. However I will keep monitoring and see if there's anything strange

[XhstormR]

After completely exiting Ghostty and then re-entering it (without entering tmux), Chinese characters are rendered correctly, and rendering also works correctly after enter tmux.

However, if I enter tmux first, then rendered in tmux, the Chinese fonts are rendered incorrectly.

[hanxi]

The problem recurred when I reopened the MacBook the day after closing it. System version: 26.2 . Tmux version: 3.6a.

[hanxi]

Temporary repair steps:

1. close ghostty window.
2. run cat cjk_test.txt .
3. run tmux att -d .
4. run cat cjk_test.txt .

[danielwe]

That's interesting. I wonder if it's the sleep and reawakening that's actually the key here, rather than tmux. Next time you put your laptop to sleep, could you make sure to have a Ghostty window open without tmux, but with the cat cjk_test.txt output visible in the viewport?

[danielwe]

There's a known issue with some rendering stuff getting corrupted during sleep such that Ghostty only shows garbage when waking back up, but it always resets itself within a few seconds. Maybe the font collection/atlas can get similarly corrupted, but in a way that does not self-heal.

[hanxi]

I can no longer reproduce this issue, whether with tmux or without tmux.

[LittleSound]

The same issue, the displayed content keeps switching between two fonts, changing the font or restarting doesn't solve the problem. This issue occurs when the terminal scaling is at 100%. If I zoom out or zoom in the terminal, making it not 100%, then the problem disappears. I don't know why.

[zeevenn]

Use CJK fallback, seems be better.

font-family = "JetBrainsMono Nerd Font"
# CJK fallback
font-family = "Noto Sans CJK SC"

[TwinklerG]

It seems to work, but the problem often happens when ghostty has been open for a while.

[XNYu]

Possible root cause after some local testing:

macOS's CTFontCreateForString is non-deterministic (Still not sure about it). Ghostty's CJK fallback path trusts and permanently caches its return value. When it occasionally returns AppleMyungjo (PostScript PCMyungjo, a Korean font) as the fallback for simplified-Chinese codepoints, those codepoints stay misrouted in the affected SharedGrid for its lifetime.

Evidence:

• A dump of SharedGrid.codepoints shows U+751F, U+5230, U+5C0F, U+628A and other simplified-Chinese characters mapped to face idx=3 = PCMyungjo (Korean)
• A simultaneous live re-check via resolver.getIndex agrees with the cache — the wrong value was written at first lookup, not corrupted later

My workaround for Simplified Chinese characters with font-codepoint-map

font-codepoint-map = U+3000-U+303F=PingFang SC
font-codepoint-map = U+FF00-U+FFEF=PingFang SC
font-codepoint-map = U+4E00-U+9FFF=PingFang SC

This setting will force these Unicode characters to use the given font.

[aolast]

I ran into the same issue: Chinese characters within a single line were split between Wawati TC and PingFang SC, while English remained normal. I documented my investigation in #14021, and the specific parser bug I found has now been fixed in #14022.

A broader finding may be useful here. Ghostty has two related pieces of font-resolution state: the Collection of loaded faces and SharedGrid's per-codepoint cache.

For a codepoint that has not been cached yet, Ghostty checks the existing faces in Collection order.

• If an earlier face covers it, that face is reused.
• If it does not, resolution falls through to CoreText, which can select and add another face.

This can produce per-character mixing: covered characters use the earlier face, while glyph misses use another fallback.

In my case, DC4 (U+0014) being treated as printable text was a reproducible way to insert an unexpected face into the Collection before Chinese text was resolved. That trigger is what #14022 fixes. Other triggers may still lead to the same Collection state, but this mechanism is consistent with @XNYu's SharedGrid findings above and narrows this class of mixed-font rendering to Collection order, the codepoint cache, and CoreText fallback. It also helps explain why restarting Ghostty or changing the font size can temporarily clear the symptom by creating a fresh font grid and cache.

As @zeevenn noted above, configuring an explicit CJK fallback can substantially reduce the problem:

font-family = "JetBrains Mono"
font-family = "PingFang SC"

This places a known CJK face in Ghostty's configured fallback order instead of relying on CoreText to select one on demand.

[danielwe]

Interesting, thanks for getting to the bottom of this!

There have been several discussions touching on the fact that font resolution is history dependent, i.e., the font used for a codepoint may depend on which codepoints have been printed earlier in the session. Giving precedence to already-loaded faces is a performance optimization, and this unfortunate side effect is known and understood, but so far it's been considered the right tradeoff.

I'm curious if the freak case you found, where unintentional font loading was triggered by a control character, is the root cause of the issue for everyone here. I don't know anything about traditional vs simplified Chinese and how they're represented in Unicode, but it's clear from the issue that the character sets overlap, but the fonts tend to be separate (I assume this is what the TC and SC suffixes mean). In that case, the issue of mixed fonts seems almost unavoidable any time both TC and SC text is printed in the same session, or even when only SC is used but the first printed glyph happens to be one that's shared with TC.

How relevant are these issues in practice for CJK users? What kind of font would you expect the terminal to use in the overlapping range if you first cat a TC file and then an SC file? Or do there exist joint TC&SC fonts that should always be given priority over TC-only or SC-only fonts?

[aolast]

@danielwe Interesting questions. Here is what I know

• Simplified Chinese (SC) and Traditional Chinese (TC) share most characters with conceptual glyph differences, i.e. a character is defined to have a different glyph in SC and TC no matter what kind of font it is. Also, some characters are sharing the same glyph definition.
• SC and TC have an overlap of code points.
• The two faces (PingFang SC and PingFang TC, default Chinese font on macbook) overlap heavily, and some shared Unicode codepoints have different regional glyph shapes.
• When both faces cover a character, CoreText’s locale preference influences the initial choice; when only one covers it, coverage determines the fallback. Once selected, that face may be reused for later shared codepoints, making resolution history-dependent.

In practice, ordinary TC-first or SC-first text did not cause mixing in my tests because the faces overlap broadly.

[ZHOUXIN-PM]

I encountered similar Chinese font rendering on Ghostty 1.3.1, macOS 26.7 (25G229).

Chinese text looked unusually thin and serif-like while Latin text remained normal. No font settings were configured. Before applying a workaround, ghostty +show-face reported PingFang SC for sampled Chinese characters, despite the different appearance in the running window.

Adding the following mapping and correctly reloading the configuration with Cmd+Shift+, resolved the visible problem:

font-codepoint-map = U+2E80-U+303F,U+3400-U+4DBF,U+4E00-U+9FFF,U+F900-U+FAFF,U+FF00-U+FFEF=PingFang SC

I noticed this after updating Pi coding agent to 1.3.0, but have no evidence that Pi caused it. I do not have a reliable reproducer, and long-term recurrence has not been tested.

AI assistance disclosure: Codex assisted with local diagnostics and drafting this report.

[danielwe]

As described in #9410 (comment), this may have been fixed by #14022, which is not yet part of any released version. If you're curious you could try the tip version (ghostty@tip in homebrew) and see if you experience the issue there.