Turso Python SDK

Warnings

• gotcha The package name is libsql-experimental, not turso or libsql. `pip install turso` will install a different unrelated package or fail.
  Fix: pip install libsql-experimental
• gotcha You must call conn.sync() explicitly to push local writes to the remote Turso database and pull remote changes. Without sync(), embedded replicas remain stale.
  Fix: Call conn.sync() after writes and before reads that need fresh remote data.
• gotcha conn.commit() is required after INSERT/UPDATE/DELETE. Auto-commit is not enabled by default, matching dbapi2 behavior.
  Fix: Always call conn.commit() after write operations, or use conn.executescript() which auto-commits.
• gotcha When using sync_url for embedded replicas, the first positional argument must be a local file path (e.g., 'local.db'), not an empty string or ':memory:'.
  Fix: Provide a valid local file path: libsql.connect('local.db', sync_url=url, auth_token=token)
• gotcha For remote-only connections (no local replica), pass the libsql:// URL as the first argument without sync_url. Mixing them up causes connection errors.
  Fix: Remote only: libsql.connect(url, auth_token=token). Embedded replica: libsql.connect('local.db', sync_url=url, auth_token=token).
• deprecated The package is marked 'experimental'. API surface may change between minor releases without deprecation warnings.
  Fix: Pin your version in production: libsql-experimental==0.0.49

Install

• pip install libsql-experimental Python (PyPI)

Imports

• libsql_experimental

  import libsql_experimental as libsql

  The package is named libsql-experimental on PyPI and imported as libsql_experimental. There is no 'turso' Python module.
• connect

  import libsql_experimental as libsql
  conn = libsql.connect('mydb.db', sync_url='libsql://...', auth_token='...')

  sqlite3 cannot connect to Turso remote URLs. Use libsql_experimental.connect() with sync_url and auth_token for remote Turso databases.

Quickstart

Connect to a Turso database using an embedded replica pattern with local SQLite file and remote sync.

import os
import libsql_experimental as libsql

url = os.environ.get('TURSO_DATABASE_URL', '')
token = os.environ.get('TURSO_AUTH_TOKEN', '')

# Embedded replica with local file + remote sync
conn = libsql.connect('local.db', sync_url=url, auth_token=token)
conn.sync()

conn.execute('CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)')
conn.execute('INSERT INTO users (name) VALUES (?)', ('Alice',))
conn.commit()

rows = conn.execute('SELECT * FROM users').fetchall()
for row in rows:
    print(row)

conn.sync()