GTFS Guru

A fast, native, multi-platform GTFS validator.

Try it in your browser · Documentation · Download

GTFS Guru checks your transit data for errors before it goes live on Google
Maps, Apple Maps, or any other journey planner — 110 validators over your
schedules, routes, stops, fares, and shapes, in seconds, on your own machine.

[!NOTE]
Inspired by MobilityData/gtfs-validator.
We rebuilt the validation logic from the ground up in Rust for speed, privacy,
and portability. The report shape and notice codes are closely compatible; the
rule sets are not identical.

Table of contents

• ⭐ Why GTFS Guru
• ⚙️ Installation
• 📝 Usage
  • ⌨️ Command line
  • 🐍 Python
  • 🖥️ Desktop app
  • 🌐 Browser
  • 🤖 MCP server
  • 🔁 Continuous integration
• ⚡ Performance
• 🧩 How the pieces fit
• 📕 Documentation
• 🔎 Contributing
• 📜 License

Why GTFS Guru?

• Fast native engine — parallel CSV loading keeps even 16-million-row feeds in the seconds range, with no JVM startup cost.
• Private by default — runs locally. Pre-release schedules never leave your machine.
• Everywhere you work — desktop app, CLI, Python library, Web API, WebAssembly, and an MCP server for LLM clients.
• Built for CI — SARIF, JSON, and HTML reports, status badges, exit codes, and a ready-made GitHub Action.
• Deep coverage — 110 validators, optional Google-specific rules, and a --thorough mode.
• Fixes, not just complaints — --fix writes a repaired copy of the feed and validates it again.

Installation

Desktop app — download the installer for macOS, Windows, or Linux from the
releases page, then
drag your gtfs.zip onto the window. No command line involved.

Command line — macOS and Linux:

curl -fsSL https://raw.githubusercontent.com/abasis-ltd/gtfs.guru/main/scripts/install.sh | bash

Windows PowerShell:

iwr -useb https://raw.githubusercontent.com/abasis-ltd/gtfs.guru/main/scripts/install.ps1 | iex

Python — for notebooks and ETL pipelines (Python 3.8+):

pip install gtfs-guru

Also available with cargo install gtfs-guru. Every platform archive, the
installer's environment variables, and building from source are in the
installation guide.

Usage

Every surface below runs the same Rust engine and emits the same notice codes,
so a feed that passes in CI passes in the desktop app.

Command line

# Validate a feed; writes report.json, report.html, and system_errors.json
gtfs-guru -i gtfs.zip -o ./report

# Validate straight from a URL
gtfs-guru -u https://example.com/gtfs.zip -o ./report

# Fail a CI job on any error, and hand SARIF to your code scanner
gtfs-guru -i gtfs.zip -o ./report --fail-on error --sarif gtfs.sarif.json

# See what a repair would change, then write a fixed copy
gtfs-guru -i gtfs.zip -o ./report --fix-dry-run
gtfs-guru -i gtfs.zip -o ./report --fix

# Compare a feed update and fail on new errors
gtfs-guru diff old.zip new.zip --fail-on-new-errors

Full option list, subcommands, badges, and CI recipes: usage guide.

Python

A native extension rather than a subprocess wrapper, for notebooks and ETL
pipelines:

import gtfs_guru

report = gtfs_guru.validate("gtfs.zip")
print(f"Valid: {report.is_valid}, notices: {len(report.notices)}")
report.save_html("validation_report.html")

for notice in report.notices:
    if notice.severity == "ERROR":
        print(notice.code, notice.message)

Every attribute of the report object: Python API.

Desktop app

Drag a gtfs.zip onto the window and read the result — no command line, no
upload. Errors that carry coordinates are plotted, so a stop placed far from
its shape is visible rather than merely counted.

Installers for macOS, Windows, and Linux are on the
releases page.

Browser

gtfs.guru runs the validator as WebAssembly inside the
tab. The feed is never uploaded — nothing to send, nothing to store — and the
same page also compares two feeds against each other.

How the WASM build works, and how to embed it: browser guide.

MCP server

gtfs-guru-mcp lets an LLM client validate feeds itself and answer questions
about the result, with concrete rows and IDs rather than only counts.

Install it with cargo install gtfs-guru-mcp (or take the archive from the
releases page), then
point your client at the directory holding your feeds:

{
  "mcpServers": {
    "gtfs-guru": {
      "command": "gtfs-guru-mcp",
      "args": ["--allow-dir", "/path/to/feeds"]
    }
  }
}

The tool list, the HTTP mode, and the token setup: LLM guide.

Continuous integration

Validate on every push with the bundled GitHub Action:

- uses: actions/checkout@v4
- uses: abasis-ltd/gtfs.guru/action@v1
  with:
    feed: feed.zip
    fail-on: error

It fails the job on errors, writes JSON and HTML reports into the output
directory, pushes SARIF to GitHub code scanning, and can emit a status badge
for your README.

Performance

Apple M3 Pro, warm page cache, each tool writing its normal report files:

On the small feeds in test-gtfs-feeds/ (295 cases, median 1.6 KB), where JVM
startup is most of the run rather than the validation work, the gap against the
canonical validator widens to a median of 88x (28-196x; 43% of cases above
100x).

Setup, caveats, and commands to reproduce: benchmarks.

How the pieces fit

One validation engine, one report layer, and a thin adapter per surface. The
adapters share the rule set and the notice codes; none of them reimplements
validation.

flowchart TD
    subgraph engine["Shared engine"]
        direction LR
        model["gtfs-guru-model<br/><i>feed types, string pool</i>"]
        core["gtfs-guru-core<br/><i>loading + 110 validators</i>"]
        profile["gtfs-guru-profile<br/><i>feed statistics</i>"]
        report["gtfs-guru-report<br/><i>JSON · HTML · SARIF</i>"]
        model --> core
        core --> profile
        core --> report
        model --> profile
        model --> report
    end

    engine --> cli["gtfs-guru<br/><i>CLI · GitHub Action</i>"]
    engine --> gui["gtfs-guru-gui<br/><i>desktop app · Tauri</i>"]
    engine --> wasm["gtfs-guru-wasm<br/><i>browser · WebAssembly</i>"]
    engine --> web["gtfs-guru-web<br/><i>HTTP service</i>"]
    engine --> python["gtfs-guru-python<br/><i>pip install · PyO3</i>"]
    engine --> mcp["gtfs-guru-mcp<br/><i>MCP server for LLM clients</i>"]

Each surface links only the engine crates it needs, not all four — the exact
per-crate dependencies, and the directory each crate lives in, are in
CONTRIBUTING.md.

Rust throughout, with Tauri for the desktop shell, wasm-bindgen (and rayon
where the browser allows threads) for the WebAssembly build, and PyO3 for the
Python extension.

Documentation

Contributing

Contributions are very welcome — new rules, bug fixes, documentation.

git clone https://github.com/abasis-ltd/gtfs.guru
cd gtfs.guru
cargo test --workspace

You will need Rust; on Linux, also the
system dependencies. See
CONTRIBUTING.md for the project layout, the review workflow,
and the style guide, and CODE_OF_CONDUCT.md for community
expectations.

Found a security issue? Please follow SECURITY.md rather than
opening a public issue.

License

Apache-2.0. Free to use for everyone.