Terminal support

We ran the same tests in six macOS terminals. Each terminal was asked directly what it supports, then drew a test pattern and a real mapterm frame, then ran the viewer with satellite imagery. All screenshots on this page come from those runs.

At a glance

	Ghostty	kitty	WezTerm	iTerm2	Alacritty	Terminal.app
Overall	Excellent	Excellent	Very good	Good	Good	Usable
24-bit color	✅	✅	✅	✅	✅	✅
Braille lines	✅	✅	✅	✅	✅	✅
Icons stay in one cell	✅	✅	✅	⚠️	⚠️	⚠️
CJK labels	✅	✅	⚠️	✅	✅	✅
Satellite as real images	✅	✅	✅	✅	❌	❌
Images detected automatically	✅	✅	✅	❌
Synchronized output	✅	✅	✅	✅	✅	❓
SGR mouse	✅	✅	✅	✅	✅	❓
Pixel mouse (smooth scrolling)	✅	✅	✅	❌	❌	❓

✅ works · ⚠️ works with a flaw · ❌ not supported · ❓ the terminal didn’t answer the query (it may still work).

Icons: iTerm2, Alacritty and Terminal.app draw circled-letter icons (Ⓡ Ⓜ Ⓑ) wider than their cell, over the next character.
CJK: WezTerm’s default font is missing some CJK characters.
Satellite: WezTerm shows thin seams between image pieces. iTerm2 needs MAPTERM_GRAPHICS=kitty. Alacritty and Terminal.app fall back to one color per cell.
Mouse: these rows are what each terminal reported about itself; clicks and drags weren’t automated. Ghostty draws braille itself rather than from a font.

Use Ghostty or kitty for the best results; WezTerm is close behind. In iTerm2 set MAPTERM_GRAPHICS=kitty to get real satellite images. Alacritty and Terminal.app draw the vector map well but show satellite imagery as blocky cell colors.

Satellite imagery

The same command in each terminal: mapterm --raster esri --at 38.8853,-77.0386 -z 15.

Ghostty: Esri imagery of the Tidal Basin as real images under the map’s labels and roads

The test pattern

Each terminal drew a 24-bit color ramp, braille blocks and diagonals, map icons between bars (each bar should line up with the ascii row below it), and CJK characters (two cells each).

Ghostty test pattern: smooth color ramp, even braille, icons inside their cells

Each terminal

Ghostty

Excellent. Everything mapterm uses works and is detected automatically. Ghostty draws braille itself, so dots line up whatever font you choose, and map icons stay inside their cell. It answered every query: synchronized output, SGR and SGR-pixels mouse, kitty graphics, and its cell size in pixels.

The experimental smooth scrolling needs the Ghostty Smooth fork; stock Ghostty runs mapterm normally.

kitty

Excellent. Everything works and is detected (TERM=xterm-kitty, KITTY_WINDOW_ID). kitty created the graphics protocol mapterm uses for images.

Very faint lines can show where image pieces meet, visible over flat areas like water.

WezTerm

Very good. Everything works and images are detected (TERM_PROGRAM=WezTerm).

Thin dark seams show where image pieces meet, clearer than in kitty.
WezTerm’s default font lacks some CJK characters (one showed as a box in the test). Configure a fallback font with CJK coverage if you map East Asian places.
WezTerm keeps TERM=xterm-256color unless you install its terminfo, which doesn’t affect mapterm.

iTerm2

Good. The vector map draws well. iTerm2 also supports the kitty graphics protocol (it answered the query and drew the satellite tiles), but mapterm doesn’t recognize iTerm2 yet, so turn images on yourself:

MAPTERM_GRAPHICS=kitty mapterm --raster esri

Map icons like Ⓡ Ⓜ Ⓑ are drawn wider than their cell and overlap the character to their right. The grid stays aligned; only the icons look crowded. Check that “Treat ambiguous-width characters as double width” is off (Settings → Profiles → Text).
No pixel mouse reporting, so no smooth scrolling.
iTerm2 asks before letting a program resize its window. mapterm never does, so you won’t see that prompt from it.
y (copy as JSON) needs “Applications in terminal may access clipboard” (Settings → General → Selection).

Alacritty

Good for vector maps. Colors, braille and labels are right, and Alacritty is fast.

No image protocol: satellite and other raster layers show as one color per cell.
Map icons overflow their cell, as in iTerm2.
No pixel mouse reporting.
The Homebrew cask is disabled (it fails Gatekeeper since September 2026); install Alacritty another way, for example with Nix.

Terminal.app

Usable. On current macOS, Terminal.app shows 24-bit color (it sets COLORTERM=truecolor) and draws the braille map correctly. It answered none of the capability queries.

No image protocol: raster layers show as cell colors.
Map icons overflow their cell.
If dragging selects text instead of panning, turn on View → Allow Mouse Reporting.
Not tested: y (copy as JSON over OSC 52).
Older macOS releases may lack 24-bit color; if the color ramp in the quick check shows bands, use another terminal.

Not tested yet

Linux and Windows terminals (GNOME Terminal, Konsole, foot, Windows Terminal) and multiplexers (tmux, Zellij) haven’t been through these tests. See Terminal requirements for what to check, and run its quick check in your terminal. If mapterm misbehaves somewhere, please open an issue with your terminal and what you see.