Designed and Created by Project Moon Pi · www.projectmoonpi.com
Live Amtrak and commuter-rail positions on a map of US passenger track, in your browser.
| 🍎 Download for Mac | Open it, double-click Install Train Tracker |
| 🪟 Download for Windows | Double-click it |
Both need Python 3.11 or newer: if the computer doesn't have it, the installer offers to install it from python.org for you. The installer sets Train Tracker up as a background service with Start and Stop icons. Step by step, including Raspberry Pi, iPhone and Android: the Installation Guide (printable PDF). The downloads are also on Project Moon Pi's website: www.projectmoonpi.com/downloads.
US Train Tracker is two parts:
- A server that runs on a computer you own: a Mac, a Windows PC, a Linux box or a Raspberry Pi. It collects live positions, arrival predictions and service alerts from Amtrak and the commuter railroads every 20–60 seconds, plus each railroad's schedule and the FRA rail map, and keeps one up-to-date picture of every train.
- A map in your web browser. Open it on the same computer, or on any phone, tablet or computer on the same Wi-Fi. The server pushes each change to the map as it happens, so trains move without reloading.
railroad feeds, schedules, alerts ─► server on your Mac / PC / Pi (port 7500) ─► browser on the computer,
FRA rail map ─► (Python) ─► phones and tablets on your Wi-Fi
Phones and tablets show the map, and it can sit on the home screen like an app, but they can't run the server: that needs a computer at home. A Raspberry Pi left on makes the map available all the time. Nothing is shared beyond your own network unless you set up remote access (the guide covers a safe way).
| Server computer | macOS 11 or newer, Windows 10 or 11, Linux, or a Raspberry Pi 4 or 5 (3B+ works, more slowly) |
| Python | 3.11 or newer from python.org (3.12+ recommended); the Mac and Windows installers install Python 3.14 if it's missing |
| Memory | about 150–200 MB while running |
| Disk | about 200 MB (app ~40 MB, downloaded maps and schedules ~140 MB) |
| Internet | always on while running: ~140 MB on first start, then about 130 MB an hour |
| To view the map | a current Safari, Chrome, Edge or Firefox; iPhone/iPad on iOS 16.4+, or Android with current Chrome (the map needs WebGL 2) |
- Zoomed out: coloured arrows (or dots when a train's direction isn't known yet) across the country.
- Middle zooms: a small top-down train (locomotive and cars) pointing the way it's going.
- Zoomed in: each train drawn to scale, car by car, bending with the real track; the track shows ballast, ties and rails, with double and triple track where NARN records it. Trains run on the right-hand track for their direction and glide along the track between updates at their reported speed. Car counts are live for SEPTA and typical for each service elsewhere.
- Freight and other track: from city-level zoom, freight main lines, industrial track, sidings and yards
appear under the passenger network (fetched by area from NARN and cached in
~/.train-tracker/narn_cells/). Abandoned, removed and out-of-service lines and rail-trails are left out. - Map layers (in the panel): switch each kind of line on or off (Amtrak and intercity, commuter, transit and tourist; freight main lines, industrial track, passing sidings, yards) and hide any railroad's track from the list of railroads in view. Choices are remembered in the browser; Show everything resets them.
- Click any track for its type, owner, subdivision, yard name and number of tracks.
- Click a train for its route, destination, next stop with its predicted time, and how late it's running, plus any service alerts about it. Follow keeps the map on the train as it moves; Share copies a link that opens straight to it.
- Stations from every railroad's schedule: click one for its next trains, live from the railroad's predictions (Penn Station-style shared stations show each railroad's board). Search finds stations too.
- Trails show where each train has been over the last 15 minutes.
- Colour trains by lateness (Map layers): green on time, amber 5–15 minutes late, red over 15.
- Service alerts in the panel, from each railroad that publishes them.
- Copy link to this view (Map layers) shares the map as you see it (
#map=zoom/lat/lon).
The easy way (Mac or Windows): download for Mac or for Windows (also on the latest release): one file. On a Mac, open the disk image and double-click Install Train Tracker; on Windows, double-click the downloaded installer. The installer:
- installs it for you (Mac:
~/Library/Application Support/Train Tracker; Windows:%LOCALAPPDATA%\Programs\Project Moon Pi\Train Tracker, or a folder you choose, though not the Desktop, Documents, Downloads or OneDrive, where ransomware protection and OneDrive stop it saving its settings), - asks whether phones on your Wi-Fi may open the map, whether it should start when you log in, and whether to put Start and Stop on your Desktop,
- sets it up as a background service (a LaunchAgent on macOS, a hidden process on Windows), and
- puts three icons in Applications › Train Tracker (Mac): Start Train Tracker starts the service and opens the map; Stop Train Tracker shuts it down; Uninstall Train Tracker removes it cleanly. On Windows the Start menu › Train Tracker has Open Train Tracker (opens the map, starting the service first if it isn't running), Start Train Tracker Service and Stop Train Tracker Service (they only start and stop it in the background); it's removed from Settings › Apps, like any program. They go on the Desktop too if you choose.
- shows a train icon in the menu bar (Mac) while it runs: its menu says since when and how many trains are on the map, and opens the map or the API keys page, or stops Train Tracker. On Windows the train icon is by the clock and stays there: green while it runs, red when it's stopped; click it for the map, right-click it to start or stop the service. Activity Monitor and Task Manager list it as Train Tracker.
Updates: when there's a newer Train Tracker, a note at the top of the map's panel says so, the Mac menu bar icon's menu offers it, and on Windows a notice pops up from the icon by the clock (once per version; click it to update). The map's About and credits has the details (Check now asks GitHub at once). On the computer running it, Update to downloads the new version in the background, checks it's the file GitHub published, and opens its installer in front: click Update there, and your settings, maps and keys are kept. Run the installer again to change your answers. With phones allowed, the map's panel shows the address and a QR code to scan. Details, the Raspberry Pi setup and troubleshooting are in the Installation Guide.
From the command line (Python 3.11 or newer):
From a release: download the .whl file from the Releases page, then:
python3 -m venv ~/train-tracker-venv
~/train-tracker-venv/bin/pip install train_tracker-*.whl
~/train-tracker-venv/bin/train-tracker
From source:
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/train-tracker
Then open http://127.0.0.1:7500. The first start takes about a minute while it downloads the
FRA track map (~4 MB) and Amtrak's schedule into ~/.train-tracker/.
| Option | Default | |
|---|---|---|
--port |
7500 |
|
--host |
127.0.0.1 |
0.0.0.0 to open it from a phone or another computer on your network |
--data-dir |
~/.train-tracker |
downloads and .env |
--allow-remote-settings |
off | let other devices change API keys on the settings page |
--open |
off | open the map in your browser once it's running |
--log-file |
write messages to a file instead of the terminal (the background service uses this) | |
--config |
bundled feeds.json |
your own feed list |
fetch-track |
re-download the NARN track map | |
--version |
Amtrak, MBTA, LIRR, Metro-North and SEPTA need no key. Four agencies hand out free developer keys:
| Agency | Where to sign up | What you get | Setting |
|---|---|---|---|
| Metra (Chicago) | metra.com/developers: accept the licence, fill in the form | API token | METRA_API_TOKEN |
| Caltrain (Bay Area) | 511.org/open-data/token: enter your email | 511 API key | API_511_KEY |
| Metrolink (Los Angeles) | GTFS-RT access page: enter your email | API key by email | METROLINK_API_KEY |
| NJ Transit | developer.njtransit.com/registration: register for RailData | username and password | NJT_USERNAME, NJT_PASSWORD |
Easiest: open API keys… in the map panel (or http://127.0.0.1:7500/settings.html). Each agency has a card with its signup link; paste the key, press Test to check it with the agency, then Save. The feed starts straight away, no restart needed, and Remove key turns it off again. Saved keys are shown only by their last four characters.
Keys are saved in ~/.train-tracker/.env (readable only by you). You can also edit that file by hand using
.env.example as a template, then restart train-tracker. Keys are personal: keep .env out of git
(it is already in .gitignore).
Keys can only be changed from the computer running train-tracker. If you run it on another machine (say a
Raspberry Pi with --host 0.0.0.0) and want to add keys from your phone, start it with --allow-remote-settings;
anyone who can reach the page on your network can then change the keys.
feeds.json ──► feeds.py one poll loop per feed (20–60 s): GTFS-RT protobuf, Amtraker JSON, NJT token flow
▼
realtime.py trip updates (next stop, predicted time, delay) and service alerts
gtfs_static.py each railroad's schedule: names, stations, timetables (rail only, cached)
▼
model.py Vehicle: key, agency, lat/lon, train, route, bearing, speed_mph, next stop, delay …
▼
app.py cache ─► WebSocket /ws (snapshot with trails and alerts, then upsert/remove diffs)
GET /api/vehicles, /api/status, /api/alerts, /api/stations,
/api/station/<feed>/<station id>
▼
web/ MapLibre map: NARN track + trains, agency filters, feed health, search
- Amtrak: Transitdocs GTFS-RT (positions, predictions and alerts in one feed), enriched from Amtrak's static GTFS.
- Amtraker fallback: only polled while the Transitdocs feed is down or empty.
- Commuter rail, no key: MBTA (filtered to
CR-routes), LIRR, Metro-North, SEPTA, MARC, VRE, RTD Denver (A, B, G and N lines) and CapMetro Rail (Austin). With keys: Metra, Caltrain (511.org), Metrolink and NJ Transit. - Schedules: each railroad's GTFS is downloaded in the background (refreshed daily, rail routes only, parsed copy cached in the data folder) for stop names, stations and the timetable. Where a feed gives predicted times but not delays (MBTA, Metro-North), lateness is worked out against the timetable.
- Positions older than 10 minutes (
stale_after_s) are dropped. Freight is out of scope.
Add an entry to feeds.json (kind: "gtfsrt", url, optional params/headers
with ${ENV_VAR} placeholders, trip_updates_url and alerts_url when the railroad publishes those separately,
static: {"url": ...} for its schedule, route_prefix or route_ids to pick the rail routes out of a feed shared
with buses) and a colour in AGENCY_COLORS in
web/app.js. Transitland and the Mobility Database list GTFS-RT URLs.
.venv/bin/pytest -q
CI runs the tests and a build on Python 3.11–3.15 for every push and pull request.
docs/INSTALL.md is the guide; after editing it, rebuild the printable copy with
python3 tools/make_guide_pdf.py (needs reportlab, Pillow and the DejaVu fonts). Releases attach the PDF.
python3 tools/make_icons.py draws the Start, Stop and Uninstall icons (a locomotive at night with the
Project Moon Pi patch) into installer/icons/, for both macOS (.icns) and Windows (.ico).
The Windows installer is a compiled C# program, with no PowerShell anywhere (antivirus programs such as Bitdefender
block a hidden PowerShell that downloads, compiles and asks for admin rights as malware). installer/windows/src/*.cs
is built three times, by installer/windows/build.sh on a Mac with Mono (against .NET Framework 4.8's reference
assemblies) or build.ps1 on Windows, into Install Train Tracker.exe, Uninstall Train Tracker.exe and
Train Tracker.exe (one program; what it does goes by its name). Train Tracker.exe is Start (--no-browser at
sign-in), Stop (--stop) and Train Tracker's own process while it runs (--run, Python hidden beneath it, so Task
Manager shows Train Tracker); the firewall change runs the same program with admin rights (--firewall). App.cs
holds what's Train Tracker's own; the other files are shared with SkyScope and Aviator Trail. Commit the rebuilt
.exe files.
- Write the changes under
## [Unreleased]in CHANGELOG.md and commit. .venv/bin/python tools/release.py 0.2.0: bumps the version, dates the changelog, runs the tests, commits and tags.git push && git push origin v0.2.0: the Release workflow checks the tag matches the version, builds the wheel and source archive, and publishes a GitHub Release with the changelog entry as its notes.
- NJ Transit endpoints (
/api/GTFSRT/getToken,/getVehiclePositions) follow the RailData API pattern but are untested with real credentials; Metra, Caltrain and Metrolink are also untested without keys. - Metra's schedule needs its API key and NJ Transit's needs an account login, so neither is loaded yet; their trains show without station names or boards.
- SEPTA's predictions give only how late a train is, not stop-by-stop times, so SEPTA station boards are empty.
- VRE runs at rush hour only; its feeds are empty the rest of the day. Sounder, South Shore, Tri-Rail, SunRail, Brightline and others don't publish an open live feed (Sounder needs a Puget Sound OneBusAway key).
- NARN stores one centreline per route, so the track a train is on is inferred (right-hand running), not known.
- Car counts are typical for each service except SEPTA, whose feed lists the cars.
- Freight track is shown, but not freight trains: railroads don't publish live freight positions.
- Help installing or using Train Tracker, or a bug to report: email support@projectmoonpi.com, or see the support page. You can also open an issue on GitHub.
- Anything else (business, partnerships, the press): sales@projectmoonpi.com.
- Website: www.projectmoonpi.com
Live data feeds (each under its provider's terms of use):
- Amtrak positions: Transitdocs GTFS-Realtime feed
- Amtrak fallback: Amtraker API by Piero Maddaleni, ODC-By 1.0
- MBTA Commuter Rail: MBTA V3/GTFS-RT, MBTA Developer license
- LIRR and Metro-North: MTA GTFS-RT feeds, MTA data terms
- SEPTA Regional Rail: SEPTA GTFS-RT
- MARC: Maryland Transit Administration GTFS-RT
- VRE: Virginia Railway Express GTFS-RT
- RTD commuter rail: RTD Denver GTFS-RT
- CapMetro Rail: Capital Metro GTFS-RT via data.texas.gov
- Metra, Caltrain (511.org), Metrolink and NJ Transit: their GTFS-RT feeds, with your own keys
Data and reference
- Track geometry: FRA North American Rail Network lines, public domain
- Schedules, routes and stations: each railroad's published GTFS (Amtrak, MBTA, MTA LIRR and Metro-North, SEPTA, Caltrain via Trillium, Metrolink, MARC, VRE, RTD, CapMetro), under each agency's data terms
- NJ Transit RailData endpoints: jtarrio/raildata (Apache-2.0), used as reference
Code, map and fonts
- MapLibre GL JS 6.16.0, BSD-3-Clause (included in
web/vendor/, with its licence) - Basemap tiles: © OpenFreeMap, © OpenMapTiles, map data © OpenStreetMap contributors (ODbL)
- Noto Sans (via the OpenFreeMap glyphs), SIL Open Font License 1.1
- Python (PSF License), which the Mac and Windows installers download from python.org when it's missing
- aiohttp, Apache-2.0
- Mac menu bar icon (installed copies): pystray (LGPL-3.0), Pillow (MIT-CMU) and, on a Mac, PyObjC (MIT)
- Windows installer: C# on Microsoft's .NET Framework 4.8 (Windows Forms), built with Mono's C# compiler (Roslyn, MIT); shared with Project Moon Pi's SkyScope
- gtfs-realtime-bindings, Apache-2.0
- protobuf, BSD-3-Clause
- certifi (Mozilla's CA certificates), MPL-2.0
- qrcode-generator 1.4.4 by Kazuhiko Arase, MIT (the "Open on your phone" QR code; included in
web/vendor/) - Printable guide: reportlab (BSD) and DejaVu Sans (Bitstream Vera / DejaVu licence)
- Development: pytest (MIT), build (MIT)
Logo: Project Moon Pi. The animated splash (lens flare, flickering lander engines, twinkling stars, metal
sheen) is ported from the Project Moon Pi M.O.S.S. dash; tools/make_splash_fx.py (needs numpy, scipy and
Pillow) maps the logo for it and only needs re-running if the logo changes.
Built with Claude Code (Anthropic).
MIT; see LICENSE. Data sources keep their own terms (see above). The Project Moon Pi name and logo belong to Project Moon Pi and are not covered by the MIT license.