Terminal requirements

Use a modern terminal

mapterm is made for Ghostty, kitty or WezTerm. They support everything below, including satellite imagery as real images. Other terminals can show the map too, but expect some of the problems on this page.

A map pushes a terminal harder than most programs. Every cell can have its own foreground and background color, lines are built from braille dots that must meet exactly, and panning redraws the whole screen many times a second.

What mapterm needs

Feature	What mapterm uses it for	Without it
24-bit color	Every fill, line and label color. mapterm always sends 24-bit colors and has no 256-color fallback.	Wrong, banded or garish colors; some terminals ignore the colors entirely.
Braille that fills the cell	Roads, rivers and borders are braille dots, 2×4 per cell.	Gaps between rows, misaligned dots, or lines that change width from cell to cell.
Mouse reporting (SGR)	Drag, wheel zoom, click, inspect.	Dragging selects text and scrolling moves the terminal’s scrollback instead of the map.
Fast full-screen redraws	Panning and zooming redraw every cell, up to 60 times a second while animating.	Lag and stutter while dragging or after a fling.
Kitty graphics protocol	Satellite and other raster tiles as real images under the map.	Rasters fall back to one color per cell. Usable, but blocky.
Window size in pixels	Placing and scaling kitty images exactly.	mapterm assumes 9×20 pixel cells, so images can be the wrong size.
Synchronized output	Images and text change together in one frame.	Brief flicker while panning a raster layer.
OSC 52 clipboard	y in inspect mode copies a feature as JSON.	y does nothing.

Ghostty, kitty and WezTerm support all of these. In Ghostty and kitty, braille is drawn by the terminal itself rather than taken from a font, so the dots line up whatever font you use.

Other terminals

See Terminal support for test results and screenshots from Ghostty, kitty, WezTerm, iTerm2, Alacritty and Terminal.app. In short:

• iTerm2 draws the map well and supports kitty images, but mapterm doesn’t detect it yet: run it with MAPTERM_GRAPHICS=kitty.
• Alacritty and macOS Terminal.app (on current macOS) draw the vector map well, but have no image protocol, so satellite imagery is blocky cell colors. Map icons look crowded in all three.
• Older or basic terminals, like the Linux console, PuTTY, screen or Terminal.app on older macOS, are where the problems below come from. Install one of the recommended terminals instead; they’re free.

Pitfalls and fixes

Colors look wrong

The terminal doesn’t support 24-bit color, or something between mapterm and the terminal strips it (tmux without 24-bit color set up, or screen). Test it:

printf '\e[48;2;225;160;70m  amber  \e[48;2;22;42;70m  navy  \e[0m\n'

If you don’t see an amber and a navy block, the terminal can’t show mapterm’s colors. In tmux (3.2 or newer), tell it your outer terminal has 24-bit color, using the $TERM you have outside tmux:

~/.tmux.conf

set -as terminal-features ',xterm-ghostty:RGB,xterm-kitty:RGB,xterm-256color:RGB'

Lines are dotted, gappy or misaligned

The terminal draws braille from a font. If your font has no braille, another font fills in, often with a different width or height, so the dots no longer line up. Also check the line spacing: anything above 1.0 leaves gaps between rows of dots and stripes in filled areas.

• Use a terminal that draws braille itself (Ghostty, kitty).
• Or use a monospace font that includes braille, and keep line spacing at 1.0.

Test it; the blocks should touch, with no gaps or lines between them:

printf '⣿⣿⣿⣿⣿⣿\n⣿⣿⣿⣿⣿⣿\n'

Labels are shifted, or icons look too wide

Map icons like Ⓡ, Ⓜ, ✈ and ⋔ are “ambiguous width” characters. They take one cell, but iTerm2, Alacritty and Terminal.app draw some of them wider, so they overlap the next character (the grid itself stays aligned). Worse, a terminal set to treat ambiguous-width characters as double width moves them to two cells and pushes the rest of the row out of place: turn that option off (in iTerm2: Settings → Profiles → Text, “Treat ambiguous-width characters as double width”). Ghostty, kitty and WezTerm keep them inside the cell.

Dragging selects text, or scrolling scrolls the terminal

Mouse reporting is off.

• macOS Terminal.app: View → Allow Mouse Reporting.
• tmux: set -g mouse on.
• Many terminals bypass mouse reporting while you hold Shift; let go of Shift.

It lags while panning

The terminal can’t redraw fast enough. GPU-rendered terminals like Ghostty, kitty and WezTerm keep up at full screen; older terminals often don’t. A smaller window also helps.

Satellite imagery is blocky

You’re seeing cell colors, not images. Either the terminal doesn’t support kitty graphics, or mapterm didn’t detect it. mapterm recognizes Ghostty, kitty, WezTerm and herdr from TERM_PROGRAM, TERM and KITTY_WINDOW_ID. Those often don’t reach it:

• Over SSH, TERM_PROGRAM usually isn’t forwarded. If your local terminal supports kitty graphics, run MAPTERM_GRAPHICS=kitty mapterm ... on the remote side.
• In iTerm2, which supports kitty images but isn’t detected yet, set MAPTERM_GRAPHICS=kitty.
• Inside tmux, mapterm uses cell colors.

If images appear at the wrong size or position, the terminal (or SSH client) isn’t reporting its size in pixels; use MAPTERM_GRAPHICS=cells.

y doesn’t copy

Copying uses OSC 52. Some terminals don’t support it; iTerm2 asks for permission (Settings → General → Selection, “Applications in terminal may access clipboard”); in tmux, add set -g set-clipboard on.

Quick check

Run these in the terminal you plan to use:

printf '\e[48;2;225;160;70m  24-bit color  \e[0m\n'   # an amber block
printf '⣿⣿⣿⣿\n⣿⣿⣿⣿\n'                                 # a solid dotted rectangle
echo "$TERM_PROGRAM $TERM"                            # ghostty, kitty or WezTerm for images

Then try mapterm --snapshot 80x24 --format ansi: it prints a colored map without taking over the screen, so you can see how your terminal draws it.