gtfslint

Fast, pure-Python GTFS Schedule validator and quality report that runs in CI.

gtfslint checks a GTFS Schedule feed (a .zip archive or a folder) against the specification, reports every problem with a stable rule code, a severity and the exact file/line/field, and computes quality metrics such as service span, trips per day and headways. It is a pip install away, has no compiled dependencies, and validates a feed with one million stop_times.txt rows in about seven seconds.

The canonical MobilityData GTFS Validator is a Java application. gtfslint does not replace it. It covers the checks that catch most broken feeds and fits where a Python tool works better: pre-commit hooks, GitHub Actions, data pipelines and notebooks. When a rule matches a MobilityData notice, the notice name is listed next to it, so you can compare the two reports.

Installation

pip install gtfslint-cli

The distribution on PyPI is called gtfslint-cli (the name gtfslint is too close to an existing project); the import name and the command are both gtfslint.

Python 3.9 or newer. The only dependencies are tomli on Python < 3.11 and tzdata on Windows.

Command line

gtfslint check feed.zip                       # text report, exit code 1 on errors
gtfslint check feed.zip --html report.html    # also write a self-contained HTML report
gtfslint check feed/ --format json > report.json
gtfslint check feed.zip --format github       # GitHub Actions annotations
gtfslint check feed.zip --select GL2,GL4 --ignore GL408 --fail-on warning
gtfslint stats feed.zip --html stats.html     # quality metrics
gtfslint rules                                # list every rule

check options:

Exit codes: 0 when no notice reaches --fail-on, 1 when at least one does, 2 for usage errors, invalid configuration or an unreadable feed.

GitHub Actions

- run: pip install gtfslint-cli
- run: gtfslint check gtfs/ --format github --html gtfs-report.html
- uses: actions/upload-artifact@v4
  if: always()
  with:
    name: gtfs-report
    path: gtfs-report.html

When the feed is a folder, annotations point to the exact file and line. When it is a zip archive, they are attached to the archive and the message gives the location inside it.

pre-commit

repos:
  - repo: https://github.com/YusufEminoglu/gtfslint_sdk
    rev: v0.1.0
    hooks:
      - id: gtfslint

The hook runs gtfslint check on every committed .zip feed.

Configuration

Settings are read from the nearest pyproject.toml. Command-line options override them.

[tool.gtfslint]
select = ["ALL"]               # codes, prefixes or names
ignore = ["GL401", "GL606"]
fail-on = "warning"            # error | warning | info | never
max-notices-per-rule = 1000
reference-date = "2026-11-08"  # default: today
min-stop-distance-m = 2.0      # GL502 threshold
max-parent-distance-m = 1000.0 # GL504 threshold
max-stop-distance-km = 50      # GL503 threshold for every route type (default: per type)
speed-limits-kmh = { 3 = 120, 0 = 80 }   # GL408 limits per basic route_type

Python API

import gtfslint

report = gtfslint.validate("feed.zip")          # -> gtfslint.Report
print(report.errors, report.warnings, report.infos, report.ok)
for notice in report.notices:
    print(notice.code, notice.severity.label, notice.location, notice.message)

report.write("report.html")                     # format inferred from the suffix
data = report.to_dict()                         # also to_json/to_text/to_markdown/to_github
report.exit_code(fail_on="warning")

report = gtfslint.validate(
    "feed/",
    select=["GL2", "GL4"],
    ignore=["fast_travel_between_consecutive_stops"],
    reference_date="2026-11-08",
    with_stats=True,
)

st = gtfslint.stats("feed.zip")                 # -> gtfslint.FeedStats
st.trips_per_day["2026-11-09"], st.busiest_date, st.headways[0].median_headway_min
cfg = gtfslint.load_config("pyproject.toml")    # -> gtfslint.Config
gtfslint.validate("feed.zip", config=cfg)

gtfslint.RULES maps every code to a Rule, which has code, name, severity, description, reference and mobilitydata. gtfslint.FeedError is raised when the path does not exist or is not a readable zip archive.

Quality metrics

gtfslint stats and gtfslint.stats() report:

• Counts: agencies, stops, stations, entrances, generic nodes, boarding areas, routes, trips, stop_times, shapes, services, frequency-based trips.
• Route types: number of routes per type. Extended types are listed separately.
• Service span: first and last service date, the number of active dates, and the first departure and last arrival times. Times past 24:00:00 are kept as they are.
• Trips per day: trip count for each service date, after combining calendar.txt and calendar_dates.txt. Trips in frequencies.txt are expanded into their departures. The busiest date is reported separately.
• Headways per route and direction: minimum, median, mean and maximum headway in minutes, and the number of departures, on the busiest date or on --date. Vehicle-hours for the same date.
• Coverage: bounding box of stops and shape points (lon/lat).
• Shapes: percentage of trips whose shape_id resolves to a shape.
• Completeness: percentage of stops with wheelchair_boarding, trips with wheelchair_accessible, trips with bikes_allowed (value 1 or 2), and stops with coordinates.

Rules

Every rule has a code (GL + three digits), a snake_case name, a default severity and a link to the part of the GTFS Schedule reference it enforces. The last column gives the matching MobilityData validator notice, when there is one. Row numbers are physical line numbers, with the header on line 1.

Notes on rule behaviour

• Field checks (GL101-GL116) apply to every field that the reference defines for agency, stops, routes, trips, stop_times, calendar, calendar_dates, fare_attributes, fare_rules, shapes, frequencies, transfers, pathways, levels, feed_info, translations and attributions. Newer files such as Fares v2, flex and networks are recognised, so they do not raise unknown_file, but their fields are not checked yet.
• Required fields that depend on other fields (GL013): stop_name, stop_lat and stop_lon for location_type 0-2; parent_station for location_type 2-4; agency_id when there are several agencies; stop_id in stop_times unless location_group_id or location_id is set; the transfer stops for transfer_type 1-3 and the transfer trips for 4-5.
• Foreign keys (GL201): trips → routes, calendars and shapes; stop_times → trips and stops; stops → parent station and levels; routes and fare_attributes → agency; frequencies → trips; transfers → stops, routes and trips; fare_rules → fare_attributes, routes and zone_id; pathways → stops; attributions → agency, routes and trips.
• Travel speed (GL408) is checked between consecutive timed stops. Untimed stops in between add to the distance. A time difference under 60 s counts as 60 s, because most feeds round times to the minute. The default limits in km/h are: tram 100, subway 150, rail 500, bus 150, ferry 80, cable tram 30, aerial lift 50, funicular 50, trolleybus 150, monorail 150, air 1200.
• Stop spacing (GL503) default maximum gap in km: 20 for urban rail and cable modes, 100 for bus, 500 for rail and ferry.
• Block overlaps (GL701) are reported when two trips with the same block_id overlap in time and their services share at least one date. Frequency-based trips are skipped.
• Expiration (GL304, GL703, GL704) is measured from --reference-date, which defaults to today. Set a fixed date in CI if builds must be reproducible.

Performance

stop_times.txt and shapes.txt are streamed one trip or one shape at a time. Small tables are kept in compact indexes, and parsed values are cached. The file is not loaded into memory. Producers almost always write the rows of a trip together. If a trip's rows are scattered through the file, gtfslint finds those trips and reads them again in a second pass, so the results stay correct.

Benchmark (benchmarks/synthetic_feed.py, a synthetic zipped feed with 100 routes, 50,000 trips, 2,000 stops and 1,000,000 stop_times rows, Python 3.12 on a Windows laptop):

Development

pip install -e ".[dev]"
python -m pytest --cov=gtfslint
python -m ruff check . && python -m ruff format --check src tests
python -m mypy src
python benchmarks/synthetic_feed.py /tmp/gtfs-bench

The tests use a small synthetic feed, tests/data/valid_feed, which passes every rule. tests/test_rules.py has one broken variant of it per rule.

License

MIT © Yusuf Eminoğlu. See LICENSE.