Skip to main content

Note: This is a community-maintained fork. The original package was removed from PyPI by its author and cannot be restored. This repository continues development and publishing under the same package name.

A Python library for reading and writing Garmin FIT files — practical for common Activity, Workout, and Course workflows.

What works / what we do not claim (capability matrix, validation levels, encode policies): docs/CAPABILITY_BOUNDARY.md.

Long-term strict-conformance roadmap (target architecture, not current guarantees): docs/FIT_CONFORMANCE_DESIGN.md.

Profile in use: 21.222.0 (fit_tool.SDK_VERSION).

Installation

Runtime has no third-party dependencies.

uv add fit-tool
# or
python3 -m pip install --upgrade fit-tool

Optional profile regeneration (maintainers only):

uv add 'fit-tool[gen]'   # openpyxl, inflection, jinja2
uv run gen-profile

CLI

fit-tool activity.fit                 # → CSV
fit-tool -t fit -o out.fit in.fit
fit-tool -h

Public API

Import the stable surface from the package root:

from fit_tool import (
    FitFile,
    FitFileBuilder,
    EncodeMode,
    EncodeOptions,
    ConformanceLevel,
    ProfileScope,
    validate_fit_file,
    FitError,
    FitParseError,
    FitCRCError,
    FitValidationError,
    PROTOCOL_VERSION,
    SDK_VERSION,
)
Symbol Role
FitFile Load, inspect, stream, serialize, validate
FitFileBuilder Build FIT files from messages
EncodeMode / EncodeOptions PRESERVE vs CANONICAL encode policies
validate_fit_file / ConformanceLevel / ProfileScope Composable validation
FitError and subclasses Typed parse / CRC / encode / validation errors
PROTOCOL_VERSION / SDK_VERSION Bundled protocol and Profile version strings

Profile messages are not re-exported at the root:

from fit_tool.profile.messages.file_id_message import FileIdMessage
from fit_tool.profile.messages.record_message import RecordMessage
from fit_tool.profile.profile_type import FileType, Sport
Mode API
Create RecordMessage()
Decode projection RecordMessage.from_definition(definition, ...)

Deep imports (from fit_tool.fit_file import FitFile) still work; prefer the package root for new code.

Examples

Read and convert to CSV

from fit_tool import FitFile

fit = FitFile.from_file("activity.fit")
fit.to_csv("activity.csv")

Stream large files (bounded memory)

from fit_tool import FitFile

for record in FitFile.iter_file("activity.fit"):
    process(record)  # CRC checked when the iterator is exhausted

Build a small Activity

from fit_tool import FitFileBuilder
from fit_tool.profile.messages.file_id_message import FileIdMessage
from fit_tool.profile.messages.record_message import RecordMessage
from fit_tool.profile.profile_type import FileType, Manufacturer

builder = FitFileBuilder(auto_define=True)
file_id = FileIdMessage()
file_id.type = FileType.ACTIVITY
file_id.manufacturer = Manufacturer.DEVELOPMENT
file_id.product = 0
file_id.serial_number = 1
file_id.time_created = 1_700_000_000_000
builder.add(file_id)

record = RecordMessage()
record.timestamp = 1_700_000_000_000
record.heart_rate = 120
builder.add(record)

data = builder.build_bytes()
# FitFileBuilder(strict=True) also runs WIRE + PROFILE(CORE) + FILE_TYPE
# (Activity needs lap/session/activity messages — see examples/).

Validate

from fit_tool import FitFile, ProfileScope, validate_fit_file, ConformanceLevel

fit = FitFile.from_file("activity.fit")
report = fit.validate()
if report.has_errors:
    print(report.errors)

# Opt-in deeper PROFILE rules (never the default for strict)
validate_fit_file(fit, profile_scope=ProfileScope.FULL)

Encode modes

from fit_tool import EncodeMode, FitFile

fit = FitFile.from_bytes(raw)
fit.to_bytes()                              # PRESERVE (default)
fit.to_bytes(mode=EncodeMode.CANONICAL)
fit.to_bytes(mode=EncodeMode.CANONICAL, strict=True)

Details: capability boundary — encode policies.

Repository examples

uv run python fit_tool/examples/read_activity_example.py
uv run python fit_tool/examples/modify_activity_example.py
uv run python fit_tool/examples/write_workout_example.py

write_activity_example.py / write_course_example.py need extra packages (gpxpy, geopy, …).

Further documentation

Doc Contents
docs/CAPABILITY_BOUNDARY.md Supported / partial / incomplete matrix; validation & encode details
docs/FIT_CONFORMANCE_DESIGN.md Target architecture and roadmap
docs/EPIC_SHA12_RELEASE_NOTES.md Protocol-capability epic rollup notes
docs/RELEASING.md Maintainer checklist for PyPI / GitHub releases
fit_tool/tests/data/README.md Fixture inventory and gap map

Metadata

Release files for fit-tool 0.10.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for fit-tool 0.10.0
File Size Uploaded Provenance Actions
fit_tool-0.10.0.tar.gz 334.0 kB With provenance Details for fit_tool-0.10.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for fit-tool 0.10.0
File Interpreter ABI Platform Actions
fit_tool-0.10.0-py3-none-any.whl Python 3 none any Details for fit_tool-0.10.0-py3-none-any.whl

Total release size: 875.6 kB

Release files / fit_tool-0.10.0.tar.gz

Download URL fit_tool-0.10.0.tar.gz
Size 334.0 kB
Tags Source
SHA-256 checksum
How to use checksums
3537c8f424d295782eacd71b74db784839147b5ad030f3d674804483123fc3ea
BLAKE2b-256 checksum
How to use checksums
781fa1956e34f7bb38fb5353f587f63b6763790dbb78c74bf0bcd0e182291b49
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

Release files / fit_tool-0.10.0-py3-none-any.whl

Download URL fit_tool-0.10.0-py3-none-any.whl
Size 541.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
db40769827c8982c3a072e1a9e898db47fc6ba6993ac6421f8dee6d4c8a1fec5
BLAKE2b-256 checksum
How to use checksums
c88c1c3ac9d673dbcbee0c7cd8cdfe151aa91fc56d3673d1d4f7f97abdeb30a4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

Security for fit-tool 0.10.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for fit_tool-0.10.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page