CLI Reference¶
The gpx command-line interface (CLI) provides tools for validating, inspecting, editing, merging, and converting GPX files. This page shows the --help for the gpx CLI and all of its sub-commands.
gpx¶
Running gpx --help or python -m gpx --help shows a list of all of the available options and arguments:
usage: gpx [-h] [--version] {validate,info,edit,merge,convert} ...
A command-line tool for working with GPX files.
options:
-h, --help show this help message and exit
--version show program's version number and exit
commands:
Available commands
{validate,info,edit,merge,convert}
validate Validate a GPX file against the GPX 1.1 schema
info Show information and statistics about a GPX file
edit Edit a GPX file with various transformations
merge Merge multiple GPX files into one
convert Convert between GPX, GeoJSON, and KML file formats
gpx validate¶
Validate a GPX file against the GPX 1.1 schema, reporting all errors and warnings. Use --strict to also fail on warnings and --json for a machine-readable report.
Running gpx validate --help or python -m gpx validate --help shows a list of all of the available options and arguments:
usage: gpx validate [-h] [--strict] [--json] <INPUT_FILE>
Validate a GPX file against the GPX 1.1 schema, reporting all errors and
warnings.
positional arguments:
<INPUT_FILE> Path to the input GPX file
options:
-h, --help show this help message and exit
--strict Treat warnings as failures (non-zero exit code)
--json Output the validation report in JSON format
gpx info¶
Display information and statistics about a GPX file. Use --strict to validate the input against the GPX 1.1 schema first, printing warnings and aborting on schema errors.
Running gpx info --help or python -m gpx info --help shows a list of all of the available options and arguments:
usage: gpx info [-h] [--json] [--strict] <INPUT_FILE>
Display detailed information and statistics about a GPX file.
positional arguments:
<INPUT_FILE> Path to the input GPX file
options:
-h, --help show this help message and exit
--json Output information in JSON format
--strict Validate the input against the GPX 1.1 schema first; print
warnings and abort on schema errors
gpx edit¶
Edit a GPX file with various transformations. Use --strict to validate the input against the GPX 1.1 schema first, printing warnings and aborting on schema errors.
Running gpx edit --help or python -m gpx edit --help shows a list of all of the available options and arguments:
usage: gpx edit [-h] -o <OUTPUT_FILE> [--min-lat LATITUDE]
[--max-lat LATITUDE] [--min-lon LONGITUDE]
[--max-lon LONGITUDE] [--start DATETIME] [--end DATETIME]
[--split-time-gap SECONDS] [--split-distance-gap METERS]
[--simplify TOLERANCE] [--smooth WINDOW]
[--shift-time SECONDS] [--reverse] [--reverse-routes]
[--reverse-tracks] [--strip-name] [--strip-desc]
[--strip-author] [--strip-copyright] [--strip-time]
[--strip-keywords] [--strip-links] [--strip-all-metadata]
[--strip-extensions] [--precision DIGITS]
[--elevation-precision DIGITS] [--strict]
<INPUT_FILE>
Edit a GPX file with various transformations like cropping, trimming,
reversing, and stripping metadata.
positional arguments:
<INPUT_FILE> Path to the input GPX file
options:
-h, --help show this help message and exit
-o, --output-file <OUTPUT_FILE>
Path to the output file
--strict Validate the input against the GPX 1.1 schema first;
print warnings and abort on schema errors
crop options:
Crop to a geographic bounding box
--min-lat LATITUDE Minimum latitude for crop
--max-lat LATITUDE Maximum latitude for crop
--min-lon LONGITUDE Minimum longitude for crop
--max-lon LONGITUDE Maximum longitude for crop
trim options:
Trim to a date/time range
--start DATETIME Start datetime (ISO 8601 format, e.g.,
2024-01-01T10:00:00)
--end DATETIME End datetime (ISO 8601 format, e.g.,
2024-01-01T12:00:00)
split options:
Split track segments at gaps
--split-time-gap SECONDS
Split track segments where the time between
consecutive points exceeds this many seconds
--split-distance-gap METERS
Split track segments where the distance between
consecutive points exceeds this many metres
simplify options:
Simplify tracks and routes
--simplify TOLERANCE Simplify tracks and routes with the Ramer-Douglas-
Peucker algorithm using this tolerance (in metres)
smooth options:
Smooth tracks and routes
--smooth WINDOW Smooth track and route coordinates and elevations with
a moving average over this many points (an odd integer
of at least 3)
time shift options:
Shift timestamps
--shift-time SECONDS Shift all point timestamps by this many seconds (may
be negative)
reverse options:
Reverse routes and/or tracks
--reverse Reverse all routes and tracks
--reverse-routes Reverse only routes
--reverse-tracks Reverse only tracks
strip options:
Strip metadata fields
--strip-name Strip metadata name
--strip-desc Strip metadata description
--strip-author Strip metadata author
--strip-copyright Strip metadata copyright
--strip-time Strip metadata time
--strip-keywords Strip metadata keywords
--strip-links Strip metadata links
--strip-all-metadata Strip all metadata
--strip-extensions Strip all extensions
precision options:
Reduce coordinate precision
--precision DIGITS Number of decimal places for lat/lon coordinates
(e.g., 6)
--elevation-precision DIGITS
Number of decimal places for elevation (e.g., 1)
gpx merge¶
Merge multiple GPX files into a single file. Use --strict to validate every input against the GPX 1.1 schema first, printing warnings and aborting if any input has schema errors.
Running gpx merge --help or python -m gpx merge --help shows a list of all of the available options and arguments:
usage: gpx merge [-h] -o <OUTPUT_FILE> [--strict]
<INPUT_FILE> [<INPUT_FILE> ...]
Merge multiple GPX files into a single GPX file.
positional arguments:
<INPUT_FILE> Paths to the GPX files to merge
options:
-h, --help show this help message and exit
-o, --output-file <OUTPUT_FILE>
Path to the output file
--strict Validate the input against the GPX 1.1 schema first;
print warnings and abort on schema errors
gpx convert¶
Convert between GPX, GeoJSON, and KML formats. Use --strict to validate GPX input against the GPX 1.1 schema first, printing warnings and aborting on schema errors (ignored for non-GPX input).
Running gpx convert --help or python -m gpx convert --help shows a list of all of the available options and arguments:
usage: gpx convert [-h] -o <OUTPUT_FILE> [-f {gpx,geojson,kml}]
[-t {gpx,geojson,kml}] [--strict]
<INPUT_FILE>
Convert GPX files to other file formats or vice versa.
positional arguments:
<INPUT_FILE> Path to the input file
options:
-h, --help show this help message and exit
-o, --output-file <OUTPUT_FILE>
Path to the output file
-f, --from-format {gpx,geojson,kml}
Input format (default: auto-detect from file
extension)
-t, --to-format {gpx,geojson,kml}
Output format (default: auto-detect from file
extension)
--strict Validate the input against the GPX 1.1 schema first;
print warnings and abort on schema errors