Install

Quick install

Cargo

cargo install mapterm

Any platform with Rust 1.89 or newer (rustup).

Binary

A signed binary for Linux (x86-64), no Rust needed: see signed binaries below. On macOS, use Cargo.

Then try it:

mapterm                                             # the whole planet
mapterm --at 40.758,-73.9855 -z 13                  # Midtown Manhattan
mapterm --style positron                            # a light MapLibre style
mapterm --raster esri --at 38.8853,-77.0386 -z 15   # satellite under the map

Scroll to zoom, drag to pan, / to search for a place, q to quit. Use a modern terminal like Ghostty, kitty or WezTerm (see below).

mapterm is a single binary with no system dependencies: TLS is built in (rustls), and tiles are decoded by mapterm’s own PMTiles and vector tile readers.

With Cargo

With a recent stable Rust toolchain (Rust 1.89 or newer; get it from rustup):

cargo install mapterm
mapterm --help

That builds mapterm from crates.io and puts it in ~/.cargo/bin. To use it as a library instead, see Adding it.

Signed binaries

Each release has a ready-built binary for Linux, x86-64 (glibc): mapterm-<version>-x86_64-unknown-linux-gnu.tar.gz. On macOS, use Cargo until there are notarized macOS binaries.

SHA256SUMS lists every archive’s checksum, and SHA256SUMS.sig is the maintainer’s SSH signature of it. Take the trusted key from the signing keys on the maintainer’s GitHub account, not from the repository (fingerprint SHA256:LiOY0+3e/eOQFeUsG7iMovOBJui3yCAXXHlWz48c4uk). With the GitHub CLI:

# the latest release: the Linux archive and the checksums
gh release download --repo tlpinney/mapterm -p 'SHA256SUMS*' -p '*x86_64-unknown-linux-gnu.tar.gz'
gh api users/tlpinney/ssh_signing_keys --jq '.[].key | "tlpinney namespaces=\"mapterm-release\" " + .' > allowed_signers
ssh-keygen -Y verify -f allowed_signers -I tlpinney -n mapterm-release -s SHA256SUMS.sig < SHA256SUMS
sha256sum -c SHA256SUMS --ignore-missing
tar xzf mapterm-*.tar.gz

The archive unpacks to a mapterm-<version>-<platform>/ folder with the mapterm binary, its README, changelog and license. Put the binary on your PATH, for example:

install -m 755 mapterm-*/mapterm ~/.local/bin/

Each release’s notes have the same steps for that version.

From Git

You don’t need this to use mapterm, but Cargo can also build a tagged version straight from GitHub:

cargo install --git https://github.com/tlpinney/mapterm --tag v0.1.1

To work on mapterm itself, clone the repository and run it with cargo run --release -- --at 38.8895,-77.0353 -z 14. Use --release: debug builds work, but decoding and drawing tiles is much slower.

Your terminal matters

Use a modern terminal

mapterm needs 24-bit color, braille that fills the cell, and mouse reporting. Use Ghostty, kitty or WezTerm for the best results, including satellite imagery as real images. Others like iTerm2, Alacritty and macOS Terminal.app draw the map with some quirks; older or basic terminals may get colors and lines wrong. See Terminal support for tested terminals and Terminal requirements for fixes.

Where mapterm keeps things

• Vector tiles fetched over HTTP are cached for 30 days in ~/.cache/mapterm.
• Raster tiles go in ~/.cache/mapterm/raster, also for 30 days (not for keyed providers unless you pass --raster-cache).
• Nothing else is written. Delete the cache directory whenever you like.

Releases and security

Changes are listed in the changelog. To report a security problem, please use a private advisory rather than a public issue; see SECURITY.md.

Next: check your terminal, then take a quick tour.