GarminDB

3.7.0 verified Sat May 09 auth: no python

Download and analyze Garmin Connect data, including activities, health data (HR, sleep, steps), and more. Version 3.7.0 released March 2025; active development with frequent releases.

pip install garmindb

Common errors

error ModuleNotFoundError: No module named 'garmindb_cli' ↓

cause Trying to import garmindb_cli as a top-level module.

fix

Use 'from garmindb import garmindb_cli' or run the CLI as 'garmindb_cli.py' (script installed to PATH).

error garminconnect.exceptions.GarminConnectAuthenticationError: Unable to authenticate with provided credentials ↓

cause Outdated authentication method or invalid credentials.

fix

Ensure you're using the latest version (3.6.0+). The library now uses OAuth via garth. Clear any old tokens and re-authenticate with email/password.

error sqlalchemy.exc.OperationalError: (sqlite3.OperationalError) table 'activity' already exists ↓

cause Running create_tables() without first checking if tables exist, or not doing a rebuild after upgrade.

fix

Use 'garmindb_cli.py --rebuild_db' to drop and recreate all tables, or call db.rebuild_tables() instead.

error AttributeError: 'GarminConnect' object has no attribute 'get_activities' ↓

cause Using an older version (pre-3.6) where the API method names differ.

fix

Upgrade to latest version: 'pip install --upgrade garmindb'. Check docs for current API: use client.get_activities(start=0, limit=10).

Warnings

breaking Version 3.7.0 requires a database rebuild. Run 'garmindb_cli.py --rebuild_db' after upgrade or you'll get schema errors. ↓

fix Run 'garmindb_cli.py --rebuild_db' (or the equivalent Python call) once after upgrading.

breaking Starting with version 3.6.0, authentication uses the 'garth' library. Old 'garminconnect' credentials may fail. ↓

fix Re-authenticate via OAuth. The library now uses browser-based login; headless may require token refreshes.

gotcha The CLI script is installed as 'garmindb_cli.py' (not 'garmindb_cli'). Running 'garmindb_cli --help' will fail. ↓

fix Use 'garmindb_cli.py' as the command, e.g. 'garmindb_cli.py --rebuild_db'.

deprecated The 'GarminDb' class constructor no longer supports the 'db_directory' parameter. It's now auto-detected from config. ↓

fix Set 'database_dir' in your config file or use default.

Imports

GarminDb

wrong

from garmindb import GarminDB

correct

from garmindb import GarminDb

Capitalization: lowercase 'b' in 'Db'

GarminConnect
```
from garmindb import GarminConnect
```
garmindb_cli
wrong
```
import garmindb_cli
```
correct
```
from garmindb import garmindb_cli
```
garmindb_cli is a module inside garmindb package, not a top-level script

Quickstart

Initialize GarminConnect, download activities, create local database and store data.

import os
from garmindb import GarminConnect, GarminDb

# Set credentials as environment variables or directly
email = os.environ.get('GARMIN_EMAIL', '')
password = os.environ.get('GARMIN_PASSWORD', '')

# Initialize GarminConnect client
client = GarminConnect(email=email, password=password)

# Download recent activities
activities = client.get_activities(start=0, limit=10)
print(f"Downloaded {len(activities)} activities")

# Initialize database (creates local SQLite)
db = GarminDb()
db.create_tables()

# Save activities to database
for activity in activities:
    db.save_activity(activity)
print("Data saved to GarminDB database.")