Skip to main content

Mi Fitness Sync

PyPI version Python versions CI status License Ko-fi

An unofficial Python CLI for accessing Mi Fitness workout data and manually syncing activities that failed to reach Strava.

Why This Exists

Mi Fitness is the Android app used by Xiaomi wearable devices. When a workout is recorded on the watch, the data is synced to the phone over Bluetooth/BLE and then uploaded to the Mi Fitness cloud under the user's Xiaomi account.

Mi Fitness officially supports third-party integrations such as Strava. In practice, workout activities are sometimes not uploaded to Strava even though they appear inside Mi Fitness.

I created this project because I wanted a way to manually sync workouts that were recorded in Mi Fitness but never made it to Strava.

What This Is Good For

This is mainly useful if you want to:

  1. Confirm that your workouts really exist in Mi Fitness cloud storage
  2. Inspect recent activities when Mi Fitness fails to push them to Strava
  3. Pull activity data yourself instead of waiting for the official sync to work
  4. Export one or many workouts to GPX, TCX, or FIT for manual backup or re-upload
  5. Upload workouts directly to Strava with duplicate detection

Install

Python 3.12 or newer is required.

Install from PyPI:

pip install mi-fitness-sync

Or install it as a standalone tool with uv:

uv tool install mi-fitness-sync

Then run with:

mi-fitness-sync --help

Or from a checkout without installing:

uv run main.py --help

Strava API Setup

Before using any Strava commands you need a Strava API application:

  1. Go to https://www.strava.com/settings/api and create an application
  2. Set the Authorization Callback Domain to localhost (just the domain, with no protocol, port, or path)

The CLI uses http://localhost:{port}/callback as the redirect URI. Strava only matches on the domain portion, so the callback domain setting must be exactly localhost.

Quick Start

# 1. Log in to your Mi / Xiaomi account (prompts for email and password)
mi-fitness-sync login

# 2. Check auth status
mi-fitness-sync auth-status

# 3. List recent workouts
mi-fitness-sync list-activities --limit 10

# 4. List activities and show which ones are already on Strava (requires strava-login)
mi-fitness-sync list-activities --limit 10 --strava

# 5. View normalized detail for one activity
mi-fitness-sync activity-detail sid:key:1717200000 --json

# 6. Export a workout
mi-fitness-sync export-activity sid:key:1717200000 --format gpx --output run.gpx

# 7. Bulk export matching workouts
mi-fitness-sync export-activities --format gpx --since 2024-01-01 --output-dir backups

# 8. Authenticate with Strava (prompts for client ID and secret)
mi-fitness-sync strava-login

# 9. Upload a workout to Strava
mi-fitness-sync upload-to-strava sid:key:1717200000

All credentials are entered via CLI arguments or interactive prompts. There are no environment variables.

Commands

Commands that access Mi Fitness accept --state-path to override the default auth state file location. Commands that access Strava accept --strava-token-path to override the default Strava token file location.

The --verbose debug output includes request URLs that carry session tokens, so do not share it unredacted.

login

Logs into Xiaomi Passport for the Mi Fitness service and saves the auth state locally. Email and password can be passed as arguments or entered interactively when omitted. The password prompt does not echo input.

If Xiaomi requires extra verification, the CLI supports the interactive flows it can complete locally:

  1. Captcha challenges download an image to the local captcha directory and try to open it with the OS default image viewer
  2. Step-2 verification prompts for the email/SMS code in the terminal
  3. Identity verification (notificationUrl) sends a code to the account email and prompts for it in the terminal

Xiaomi can ask for a second challenge after you answer the first one, for example, identity verification after a captcha. The CLI handles each one in turn, up to 5.

At the identity verification prompt, type resend to get a new email code or cancel to stop. An empty or rejected code prompts you again. If Xiaomi cannot send the email, the error shows the verification URL so you can see which check Xiaomi asks for. Approving the sign-in in a browser does not log the CLI in, so run login again afterwards.

Examples:

mi-fitness-sync login
mi-fitness-sync login --email you@example.com --password your-password

Flags:

Flag Description
--email Mi / Xiaomi account email (prompted if omitted)
--password Mi / Xiaomi account password (prompted securely if omitted)
--state-path Override the persisted auth state file path
--verbose Enable debug logging

logout

Deletes the saved local Mi Fitness auth state.

mi-fitness-sync logout

Flags:

Flag Description
--state-path Override the persisted auth state file path

auth-status

Shows the currently saved Mi Fitness auth state.

mi-fitness-sync auth-status
mi-fitness-sync auth-status --json

Flags:

Flag Description
--json Print the full auth state as JSON
--state-path Override the persisted auth state file path

list-activities

Lists workout activities from the Mi Fitness cloud.

mi-fitness-sync list-activities --limit 10
mi-fitness-sync list-activities --since 2024-01-01 --json
mi-fitness-sync list-activities --since 2026-03-20 --strava
mi-fitness-sync list-activities --since 1717200000 --until 1719800000 --limit 50

Flags:

Flag Description
--since Inclusive start time (unix seconds or ISO-8601)
--until Inclusive end time (unix seconds or ISO-8601)
--limit Maximum activities to return (default: 20)
--category Mi Fitness category filter string
--country-code Two-letter country override (e.g. ID, GB, US); mapped to the Mi Fitness region automatically
--strava Show whether each activity is already uploaded to Strava
--strava-token-path Override the Strava token file path (used with --strava)
--json Print activities as JSON
--verbose Enable debug logging
--state-path Override the persisted auth state file path

When --country-code is omitted, the CLI uses automatic Mi Fitness region detection.

activity-detail

Fetches the normalized detail payload for one activity.

mi-fitness-sync activity-detail sid:key:1717200000
mi-fitness-sync activity-detail sid:key:1717200000 --country-code ID --json

Flags:

Flag Description
activity_id Activity ID from list-activities (positional, required)
--country-code Two-letter country override
--json Print normalized detail as JSON
--no-cache Disable the local FDS binary cache
--cache-dir Override the local FDS cache directory
--verbose Enable debug logging
--state-path Override the persisted auth state file path

Detail lookup behavior:

  1. Prefers the richer workout JSON payload when Mi Fitness exposes it
  2. Checks the Mi Fitness cloud for downloadable binary workout data (FDS files containing GPS tracks, heart rate, etc.)
  3. Can synthesize detail from FDS sport samples or GPS track points when the JSON payload is missing
  4. Attaches recoverable FDS sport-report and recovery-rate data (not consumed by exporters)
  5. Fails if neither the JSON detail nor FDS binary data is available

export-activity

Exports one activity to GPX, TCX, or FIT.

mi-fitness-sync export-activity sid:key:1717200000 --format gpx --output run.gpx
mi-fitness-sync export-activity sid:key:1717200000 --format tcx --output run.tcx.gz --gzip
mi-fitness-sync export-activity sid:key:1717200000 --format gpx --smooth-mode full --outlier-speed 7:30
mi-fitness-sync export-activity sid:key:1717200000 --format fit

Flags:

Flag Description
activity_id Activity ID from list-activities (positional, required)
--format Export format: gpx, tcx, or fit (required)
--output Destination file path (default: ~/.mi_fitness_sync/exports/<sanitized_title>_<local_start_time>.<format>)
--gzip Gzip-compress the output
--country-code Two-letter country override
--no-cache Disable the local FDS binary cache
--cache-dir Override the local FDS cache directory
--no-smooth Disable GPS smoothing entirely
--outlier-speed Max plausible speed for outlier detection, as km/h (for example 180 or 180kmh) or pace (for example 7:30 or 7:30/km)
--smooth-mode Smoothing strategy: match (default, converge toward the Mi Fitness summary distance) or full (apply the strongest smoothing pass)
--verbose Enable debug logging
--state-path Override the persisted auth state file path

Export behavior:

  1. GPX requires GPS track points in the detail payload
  2. TCX and FIT prefer track points but fall back to timestamped sport samples without coordinates
  3. GPS smoothing is enabled by default for exports that include GPS coordinates; it only adjusts latitude/longitude and leaves timestamps, heart rate, cadence, and other fields unchanged
  4. match mode tries to bring the smoothed GPS distance closer to the Mi Fitness summary distance, while full applies the largest valid smoothing window after outlier cleanup
  5. FIT generation is best-effort, so only fields present in the Mi Fitness source are included
  6. Pool swim FIT exports write one length message per pool length, with rest as idle lengths, and one lap per swim set plus one per rest period before, between, or after sets

export-activities

Exports many activities to GPX, TCX, or FIT using the same filters as list-activities.

mi-fitness-sync export-activities --format gpx --since 2024-01-01 --output-dir backups
mi-fitness-sync export-activities --format fit --category outdoor_run --workers 2
mi-fitness-sync export-activities --format tcx --limit 100 --gzip --resume-file backups/export_manifest.jsonl

Flags:

Flag Description
--since Inclusive start time (unix seconds or ISO-8601)
--until Inclusive end time (unix seconds or ISO-8601)
--limit Maximum activities to export (default: all matching activities)
--category Mi Fitness category filter string
--format Export format: gpx, tcx, or fit (required)
--output-dir Destination directory (default: ~/.mi_fitness_sync/exports/bulk)
--resume-file Resume/manifest JSONL path (default: <output-dir>/bulk_export_<format>.jsonl)
--workers Concurrent export workers (default: 2)
--overwrite Re-export files even when the output path already exists
--gzip Gzip-compress every exported file
--country-code Two-letter country override
--no-cache Disable the local FDS binary cache
--cache-dir Override the local FDS cache directory
--no-smooth Disable GPS smoothing entirely
--outlier-speed Max plausible speed for outlier detection, as km/h or pace
--smooth-mode Smoothing strategy: match (default) or full
--verbose Enable debug logging
--state-path Override the persisted auth state file path

Bulk export behavior:

  1. Streams activities page-by-page instead of building one large in-memory list
  2. Reuses the listed activity objects directly, so it avoids the extra ID lookup step used by single-activity export
  3. Writes output files atomically and records progress in an append-only JSONL manifest so reruns can resume large jobs
  4. Skips existing output files by default; use --overwrite to regenerate them
  5. Uses conservative bounded concurrency plus automatic retry/backoff for transient Mi Fitness and FDS HTTP failures
  6. Default filenames include the activity ID suffix to keep large batches collision-free

strava-login

Authenticates with Strava using the OAuth2 authorization code flow. Opens a browser for authorization, then stores the tokens locally. Client ID and secret can be passed as arguments or entered interactively.

mi-fitness-sync strava-login
mi-fitness-sync strava-login --client-id YOUR_ID --client-secret YOUR_SECRET

Flags:

Flag Description
--client-id Strava API client ID (prompted if omitted)
--client-secret Strava API client secret (prompted if omitted)
--port Local port for the OAuth callback server (default: 5478)
--strava-token-path Override the Strava token file path

The flow:

  1. Starts a temporary local HTTP server on localhost:{port}
  2. Opens the Strava authorization page in your browser
  3. After authorization, Strava redirects to the local server with an auth code
  4. Exchanges the code for access and refresh tokens
  5. Saves tokens to ~/.mi_fitness_sync/strava/tokens.json

When the saved access token has expired or is about to expire, the CLI refreshes it with the stored refresh token before filling the --strava column or uploading an activity.

strava-status

Shows the currently saved Strava auth state.

mi-fitness-sync strava-status

Flags:

Flag Description
--strava-token-path Override the Strava token file path

strava-logout

Revokes the Strava access token via the Strava API and deletes the local token file. Exits cleanly if no tokens exist. Deletes local tokens even if remote revocation fails.

mi-fitness-sync strava-logout

Flags:

Flag Description
--strava-token-path Override the Strava token file path

upload-to-strava

Uploads one Mi Fitness activity to Strava as a FIT file. The FIT file is also saved locally.

mi-fitness-sync upload-to-strava sid:key:1717200000
mi-fitness-sync upload-to-strava sid:key:1717200000 --output run.fit
mi-fitness-sync upload-to-strava sid:key:1717200000 --smooth-mode full --outlier-speed 180kmh
mi-fitness-sync upload-to-strava sid:key:1717200000 --skip-duplicate-check

Flags:

Flag Description
activity_id Activity ID from list-activities (positional, required)
--output Local FIT file save path (default: ~/.mi_fitness_sync/exports/<sanitized_title>_<local_start_time>.fit)
--country-code Two-letter country override
--skip-duplicate-check Skip checking Strava for existing activities with a similar start time
--strava-token-path Override the Strava token file path
--no-cache Disable the local FDS binary cache
--cache-dir Override the local FDS cache directory
--no-smooth Disable GPS smoothing entirely before generating the FIT upload
--outlier-speed Max plausible speed for outlier detection, as km/h or pace
--smooth-mode Smoothing strategy: match (default) or full
--verbose Enable debug logging
--state-path Override the persisted Mi Fitness auth state file path

Upload behavior:

  1. Fetches the activity detail from Mi Fitness
  2. Renders to FIT format with the same optional smoothing controls as export-activity, then saves the file locally
  3. Checks Strava for existing activities within 5 minutes either side of the start time (unless --skip-duplicate-check is set)
  4. If potential duplicates are found, prompts for confirmation before uploading
  5. Uploads the FIT file to Strava and polls until Strava finishes processing it, giving up after about a minute
  6. Prints the Strava activity URL on success
  7. The sport type is mapped from Mi Fitness to the closest Strava equivalent; unmapped types let Strava auto-detect

Project Layout

src/mi_fitness_sync/
  activity/    Activity listing, detail, region routing, normalization
  auth/        Xiaomi Passport auth and persistence
  cli/         Command-line entry point
  export/      GPX, TCX, and FIT rendering
  fds/         Mi Fitness FDS binary parsing and caching
  strava/      Strava OAuth2 auth and upload
tests/         Per-module test files mirroring the package structure, plus the release tooling test

Development

The project is managed with uv and checked with ruff and mypy in strict mode.

# Create the environment and install the development dependencies
uv sync --all-groups

# Run the test suite with coverage
uv run pytest --cov --cov-report=term-missing

# Format and lint
uv run ruff format
uv run ruff check

# Type check the package
uv run mypy

CI runs formatting, lint, and type checks on pushes to main and on every pull request, together with a build whose packaging metadata is validated. The test suite runs on Ubuntu and Windows for Python 3.12 and 3.13.

Changelog

Release notes live in CHANGELOG.md, and every published version has a GitHub release.

Local Auth Storage

By default, Mi Fitness auth state is stored in the user profile under ~/.mi_fitness_sync/auth/auth.json.

You can override that location with --state-path.

Strava tokens are stored under ~/.mi_fitness_sync/strava/tokens.json. You can override that location with --strava-token-path.

When Xiaomi requires a captcha, the image is saved under ~/.mi_fitness_sync/captcha/ and the CLI tries to open it with your OS default image app. The file is deleted on a best-effort basis after you respond; if deletion fails, the CLI prints the saved path so you can remove it manually.

Both files contain sensitive credentials and should not be shared or committed to version control.

Limitations

  1. This is an unofficial project and is not affiliated with Xiaomi, Mi Fitness, or Strava.
  2. Parts of the Xiaomi login flow had to be pieced together from app behavior and decompiled code.
  3. Xiaomi may change endpoints, cookies, signatures, or response formats at any time.
  4. Some accounts may require captcha or app approval flows that are not fully automated here. Step-2 verification (SMS/email code) and identity verification by email code are supported interactively.
  5. Detail retrieval currently depends on the raw huami_sport_record payload shape used by the Android app; Xiaomi may change that format without notice.
  6. FDS download-url metadata does not guarantee the corresponding cloud object is still downloadable, so some workouts still cannot be enriched from FDS.
  7. GPX export is unavailable for workouts where Mi Fitness does not expose GPS track points.
  8. TCX and FIT require timestamped export points. The exporter uses GPS track points directly when they are present in the normalized detail and otherwise falls back to timestamped sport samples; if neither source exists, those exports are unavailable.
  9. FIT export is best-effort and may omit fields when Mi Fitness does not provide enough source data for a fuller activity file.

Security Notes

  1. The CLI accepts Mi account and Strava client credentials either on the command line or via interactive prompts.
  2. Command-line arguments may be persisted in shell history or process listings depending on your environment, so interactive prompts are safer on shared machines.
  3. The persisted Mi Fitness auth state and Strava token files contain sensitive session data and should be protected.

If you use this on a shared machine, treat the local auth state like a credential.

Sponsor

If mi-fitness-sync saves you time, you can support its development on Ko-fi.

License

MIT. See LICENSE.

Metadata

Release files for mi-fitness-sync 0.1.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 mi-fitness-sync 0.1.0
File Size Uploaded Provenance Actions
mi_fitness_sync-0.1.0.tar.gz 197.0 kB With provenance Details for mi_fitness_sync-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for mi-fitness-sync 0.1.0
File Interpreter ABI Platform Actions
mi_fitness_sync-0.1.0-py3-none-any.whl Python 3 none any Details for mi_fitness_sync-0.1.0-py3-none-any.whl

Total release size: 287.7 kB

Release files / mi_fitness_sync-0.1.0.tar.gz

Download URL mi_fitness_sync-0.1.0.tar.gz
Size 197.0 kB
Tags Source
SHA-256 checksum
How to use checksums
9bc1c071a4bca18a5d7e14d556bfa100c5272f7a6ccaf8087868b27e76816937
BLAKE2b-256 checksum
How to use checksums
8e1a7d80c1b8ea9f821a347fffcae249a66ba23fe3c3f6316992585b3b26cf34
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 / mi_fitness_sync-0.1.0-py3-none-any.whl

Download URL mi_fitness_sync-0.1.0-py3-none-any.whl
Size 90.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f09b7c8695aef38abfb95baa344047eff67ba179c501fd980bb88836c5e93226
BLAKE2b-256 checksum
How to use checksums
72f7f53fe75beb038405c21145bc982e2194648bfb6963ba4da2c4b11c28cf4c
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 mi-fitness-sync 0.1.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 mi_fitness_sync-0.1.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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

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