FlightTracer

Turn an aircraft tail number, ICAO hex, or ADS-B Exchange link into a flight map, altitude and speed charts and reusable data.

pip install flight-tracer
flight-tracer trace --icao a40442

No date means recent activity. For a historical flight, add --date YYYY-MM-DD.

Example: An LAPD helicopter, N224LA, patrolling on an early Saturday morning.

Start with what you have

Tail-number lookup requires pip install "flight-tracer[faa]". A callsign such as FDX9756 cannot currently be used as an input; first find the aircraft's ICAO hex or tail number for that flight and date.

Common recipes

Fetch a date range and render every leg

flight-tracer trace --n-number N868FD \
  --start 2026-09-26 --end 2026-09-27 --leg all

Both dates are included. Each detected leg gets its own folder, plus an overview map. Use --leg 1 for one leg or --leg latest for the most recent detected leg.

Select a time window

flight-tracer trace --icao a9a1ad --date 2020-01-26 \
  --after 2020-01-26T09:00:00 --before 2020-01-26T10:00:00 \
  --window-timezone America/Los_Angeles --timezone America/Los_Angeles

Bounds are inclusive. Timestamps without an offset default to UTC unless --window-timezone is set. --timezone controls display separately. For older archives, --infer-legs can optionally detect explicit ground stops. See the detailed January 26 case study.

Make a portrait map with local times

flight-tracer trace --icao a40442 --date 2026-09-16 \
  --aspect-ratio 9:16 --timezone America/Los_Angeles

Portrait outputs are 1080 × 1920. Local times appear alongside UTC; exported timestamps keep their full precision.

Change the basemap and gap threshold

flight-tracer trace --icao a40442 --date 2026-09-16 \
  --background osm --gap-minutes 2

Connections across tracking gaps longer than two minutes are dashed. The default threshold is five minutes. The default basemap is esri-light; see all map styles, including Mapbox with your own token.

Add a headline and label locations

flight-tracer trace --icao a40442 --date 2026-09-16 \
  --title "LAPD helicopter circles the San Fernando Valley" \
  --label "34.2098,-118.4898,Van Nuys Airport" \
  --label "34.2597,-118.4134,Whiteman Airport"

--title and --dek replace the map's generated headline and time span. Each --label takes latitude, longitude and text, and the map widens to include it. On multi-leg runs, the title and dek go on the overview and labels go on every map. They're saved in annotations.json, so render reuses them.

Re-render a saved run

flight-tracer render data/a40442_2026-09-16_2026-09-16 \
  --background osm --aspect-ratio 9:16 --output variants/portrait

Redraws images from the saved trace.csv without fetching the flight again. Data files are not rewritten. Saved annotations carry over; pass --title, --dek or --label to replace them.

Save your usual settings as presets

# ~/.config/flight-tracer/presets.toml
[default]
timezone = "auto"

[social]
aspect-ratio = "9:16"
output = "~/Desktop/social"

flight-tracer trace --icao a40442 --preset social
flight-tracer presets   # show the file's location and contents

[default] always applies. --preset NAME adds a named table on top, and flags override both. Keys are spelled like the flags. See the CLI reference for what presets can set.

Export data without charts

flight-tracer trace --icao a40442 --date 2026-09-16 \
  --no-plots --formats csv,geojson --output exports

What you get

A single-leg run writes:

data/a40442_2026-09-16_2026-09-16/
├── map.png           # Route, start and last location, dates, attribution
├── altitude.png      # Altitude over time
├── speed.png         # Ground speed over time
├── trace.csv         # Recorded points and decoded fields
├── points.geojson    # Point geometries
├── line.geojson      # Routes by leg
├── summary.json      # Aircraft metadata, times and statistics
├── selection.json    # Time bounds, leg selection and ground-filter settings
└── annotations.json  # Custom title, dek and location labels, reused by render

For several detected legs, the root contains the full data and overview.png; subfolders such as leg1_FDX9756/ contain each leg's data and charts. Interactive runs ask which leg to use; --leg all skips the prompt. Non-interactive runs default to all legs.

Running the same aircraft/date selection again writes to the same folder. Use a different --output directory to keep variants.

Installation and upgrades

Python 3.9 or newer is required. Optional extras add tail-number lookup and automatic timezone lookup:

pip install "flight-tracer[faa,tz]"
flight-tracer --version
flight-tracer trace --help

Quote extras such as [faa,tz] in zsh. To upgrade an existing installation:

pip install --upgrade flight-tracer

For local development, run this from the repository after installing dependencies:

pip install --no-deps -e .

Understand the trace

• Last location means last received position, not a confirmed landing or crash site.
• Check the data-quality notes. Each run reports tracking gaps, stale and multilaterated positions, missing metadata and how leg boundaries were found; the full set is in summary.json.
• Dashed segments approximate missing coverage. They do not establish the path flown. Exported route geometries include connections without dash styling.
• Legs use the archive's boundary flags. Older archives may lack them. Opt-in --infer-legs uses explicit ground stops and labels its results as estimates; otherwise use a time window. Seven-field historical records are supported.
• Date Line crossings are handled automatically. Maps wrap around the Pacific where appropriate; exported routes split at ±180°.
• Altitude and speed are raw, uncorrected values. Missing metadata stays empty. Times default to UTC; local time is opt-in.

More examples and reference

Contributing and releasing

Run checks with python -m pytest tests/. tests/test_visual.py compares rendered maps and charts with the reference images in tests/baseline_images/. If a change to the output is intended, regenerate them with FLIGHT_TRACER_UPDATE_BASELINES=1 python -m pytest tests/test_visual.py and review the new images before committing. Failed comparisons leave the new render and a diff in tests/visual_results/. See PUBLISH.md for the release workflow.

Credits and license

Flight data comes from ADS-B Exchange. Consider subscribing or contributing data. FAA tail-number resolution uses hangarbay. Keep the basemap attribution in exported maps.

FlightTracer is released under CC0 1.0. The bundled Inter typeface (flight_tracer/fonts/) is by The Inter Project Authors and keeps its own SIL Open Font License 1.1.