Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog and this project adheres to Calendar Versioning.

The first number of the version is the year. The second number is incremented with each release, starting at 1 for each year. The third number is for emergencies when we need to start branches for older releases.

2026.2.0 - 2026-04-27

Added

• GPX Extensions support: Added Extensions class for handling GPX extension elements from any XML namespace (e.g., Garmin’s TrackPointExtension). Extensions are now parsed, preserved, and serialized during round-trip processing, enabling lossless handling of vendor-specific data like heart rate, cadence, temperature, etc.

• New extensions field on all models that support extensions per the GPX 1.1 spec: GPX, Metadata, Waypoint, Track, TrackSegment, and Route.

Changed

• Track now inherits from PointsMixin and reuses its bounds and elevation aggregations (bounds, _points_with_ele, _eles, avg_elevation, min_elevation, max_elevation, diff_elevation, avg_speed, avg_moving_speed), eliminating duplication between Track and the segment/route mixin. Per-segment semantics are preserved for distance, duration, speed extremes, ascent/descent and the elevation profile by overriding only those properties.

• int and bool fields in __geo_interface__ properties (e.g. Waypoint.sat, Track.number, Route.number) now keep their JSON-native types.

Removed

• Removed obsolete remove_encoding_from_string function.

Fixed

• EWKB format parsing now correctly handles Z coordinates by checking the EWKB flag before the ISO WKB flag.

• gpx edit no longer drops custom XML namespace prefixes (e.g. gpxtpx, gpxx) from the source file. All edit transformations (crop, trim, reverse, precision, strip metadata) now propagate nsmap so round-trips preserve the original prefixes.

• gpx edit --min-lat 0 (and the other crop bounds) is no longer silently ignored.

• Track.elevation_profile no longer skips the first elevation-bearing point of segments after the first, and no longer raises IndexError for tracks with no segments or no points with elevation. PointsMixin.elevation_profile (used by Route and TrackSegment) similarly returns [] for empty inputs instead of crashing.

• Waypoint.speed_to no longer raises ZeroDivisionError when two waypoints share a timestamp (or either lacks one); it returns 0.0 instead. This also fixes downstream crashes in PointsMixin._speeds, max_speed, min_speed, moving_duration, and speed_profile for tracks containing consecutive points with identical timestamps.

• Waypoint.slope_to similarly returns Decimal(0) instead of raising ZeroDivisionError when two waypoints share coordinates.

2026.1.0 - 2026-01-07

Added

• New cli module with command-line interface (CLI) for common GPX operations:

  • gpx validate: Validate a GPX file

  • gpx info: Show information and statistics about a GPX file

  • gpx edit: Edit a GPX file with various transformations:

    • Crop to a geographic bounding box (--min-lat, --min-lon, --max-lat, --max-lon)

    • Trim to a date/time range (--start, --end)

    • Reverse routes and/or tracks (--reverse, --reverse-routes, --reverse-tracks)

    • Strip metadata fields (--strip-name, --strip-desc, --strip-author, --strip-copyright, --strip-time, --strip-keywords, --strip-links, --strip-all-metadata)

    • Reduce coordinate precision (--precision, --elevation-precision)

  • gpx merge: Merge multiple GPX files into one

  • gpx convert: Convert between GPX, GeoJSON, and KML formats

• New CLI reference documentation page with auto-generated help output using cog

• New io module with read_*() functions for reading file formats:

  • read_gpx(): Read GPX files

  • read_geojson(): Read GeoJSON files

  • read_kml(): Read KML files

• New convert module with from_*() functions for converting from data formats:

  • from_string(): Convert from a GPX string

  • from_geo_interface(): Convert from objects that implement the __geo_interface__ protocol (e.g., Shapely)

  • from_wkb(): Convert from Well-Known Binary bytes

  • from_wkt(): Convert from Well-Known Text strings

• New write_*() methods on the GPX class for writing to file formats:

  • write_gpx(): Write to GPX file (renamed from to_file())

  • write_geojson(): Write to GeoJSON file

  • write_kml(): Write to KML file (Google Earth format)

• New to_*() methods on the GPX class for converting to data formats:

  • to_wkt(): Convert to Well-Known Text (OGC standard)

  • to_wkb(): Convert to Well-Known Binary (OGC standard)

Changed

• Renamed GPX.to_file() to GPX.write_gpx() for consistency with other write methods.

• Replaced built-in tempfile module usage with pytest’s tmp_path and tmp_path_factory fixtures in the test suite for better test isolation and automatic cleanup.

Removed

• All aliases and proxies.

• GPX.from_file() method in favor of io.read_gpx().

• GPX.from_string() method in favor of convert.from_string().

2025.1.0 - 2025-11-29

This is a major release with a lot of breaking changes, primarily due to a complete rewrite of the architecture, and a general modernization of the package. Besides the change in architecture, this release adds comprehensive unit tests, enforces strict linting rules, and drops support folder older versions of Python. Finally, this release implements the __geo_interface__ protocol for all GPX elements that contain geopgraphic information, thus adding support for converting to GeoJSON.

Migration notes for users upgrading from 0.2.x:

1. Ensure you are using Python 3.11 or higher

2. Update constructor calls to use keyword arguments for optional parameters

3. Update field names to use GPX-standard names (e.g., trkseg instead of trksegs)

4. Remove validate=True from from_file() and from_string() calls

5. Update error handling to catch standard Python exceptions instead of gpx.errors.ParseError

Example:

# Before (0.2.x)
from gpx import GPX, Waypoint

gpx = GPX.from_file("path/to/track.gpx", validate=True)
waypoint = Waypoint()
waypoint.lat = Decimal("52.0")
waypoint.lon = Decimal("4.0")
waypoint.name = "Amsterdam"
gpx.waypoints.append(waypoint)

# After (2025.1.0)
from gpx import GPX, Waypoint
from decimal import Decimal

gpx = GPX.from_file("path/to/track.gpx")
waypoint = Waypoint(Decimal("52.0"), Decimal("4.0"), name="Amsterdam")
gpx.wpt.append(waypoint)

Added

• CLAUDE.md for easier interoperability with Claude Code.

• Comprehensive unit tests.

• Smoke test.

• Testing workflow via GitHub Actions.

• Support for Python 3.12, 3.13 and 3.14.

• More usage examples in README.md.

• __geo_interface__ protocol for all GPX elements that contain geographic information.

Changed

• Upgraded the pre-commit hooks.

• Enabled ALL rules for the ruff linter by default.

• Use the uv build backend instead of flit.

• Updated the installation instructions to make use of uv instead of pip.

• Switched the versioning scheme from semantic versioning to Calendar Versioning.

• Refactored the GPX element classes into dataclass-based models.

• Replaced lxml with the built-in ElementTree module.

• Optional dependencies to dependency groups.

• Renamed PyGPX to gpx (purely aesthetically, no changes in installation or usage required).

Removed

• Support for Python 3.7, 3.8, 3.9 and 3.10.

• The errors module.

Fixed

• Erroneous examples in the usage examples in README.md.

0.2.1 (2023-04-09)

Fixed

• Serialization of route and track numbers. #10

• Mutable default values. #11

0.2.0 (2023-04-06)

With this release, PyGPX is now fully [1] compatible with the GPX 1.1 specification.

Changes

• Added the following new modules and classes:

  • gpx.bounds.Bounds

  • gpx.copyright.Copyright

  • gpx.element.Element

  • gpx.email.Email

  • gpx.link.Link

  • gpx.metadata.Metadata

  • gpx.mixins.AttributesMutableMappingMixin

  • gpx.mixins.PointsSequenceMixin

  • gpx.mixins.PointsMutableSequenceMixin

  • gpx.person.Person

  • gpx.track_segment.TrackSegment

  • gpx.types.Latitude

  • gpx.types.Longitude

  • gpx.types.Degrees

  • gpx.types.Fix

  • gpx.types.DGPSStation

• All element classes now inherit from the new gpx.element.Element base class.

• All element classes now make use of the new element / type classes (e.g. gpx.types.Latitude), according to the GPX 1.1 specification.

• Added the gpx.errors.ParseError exception for when attempting to parse an XML element that does not exist.

• All metadata attributes have been moved to the new gpx.metadata.Metadata class, but are still accessible via the gpx.gpx.GPX class via aliases for backwards compatibility and convenience.

• Changed all duration attributes to datetime.timedelta objects (instead of floats).

0.1.1 (2023-03-31)

This release introduces a completely overhauled codebase. For this, I used my cookiecutter-python-package Python package template. As such, this release comes with much higher code quality, documentation and automation.

The API itself has not changed (and as such, there is no minor version bump).

Changes

• Completely refactored codebase, with:

  • Moved source code from ./gpx to ./src/gpx

  • Fully typed and documented

• Added documentation via Read the Docs

• Updated CI/CD via GitHub Actions

• Added pre-commit hooks w/ CI-integration

0.1.0 (2021-06-08)

Changes

• Initial release of PyGPX

---

[1]

PyGPX is not compatible with extensions from other schemas (e.g. the Garmin GPX extensions), and ignores them.