Turso Python SDK

0.0.49 verified Tue May 12 auth: no python install: stale quickstart: stale

Python SDK for Turso, a distributed SQLite database built on libSQL. Provides a dbapi2-compatible interface for connecting to local SQLite files, libSQL servers, and Turso hosted databases. The package name on PyPI is libsql-experimental (not 'turso').

pip install libsql-experimental

Common errors

error error: subprocess-exited-with-error × Building wheel for libsql-experimental (pyproject.toml) did not run successfully. ↓

cause This error often occurs on Windows, especially with Python 3.12, due to missing build tools or issues with the underlying Rust `libsql-ffi` build script, which may rely on Unix-like commands (`cp`) not natively available.

fix

Ensure you have the Rust toolchain (Rustup, Cargo) and C++ build tools (e.g., from Visual Studio Build Tools) installed. Consider using a Linux or macOS environment, or a Docker container for development, as Windows support can be challenging due to platform differences in build environments. Upgrading libsql-experimental to a newer version might also include fixes for these build issues.

error pyo3_runtime.PanicException: there is no reactor running, must be called from the context of a Tokio 1.x runtime ↓

cause This panic occurs when attempting to connect to a remote Turso database or use other async features of `libsql-experimental` without an active asynchronous runtime (like `asyncio` in Python) in the current thread or scope.

fix

Ensure that your code is run within an asyncio event loop. For example, wrap your connection and query logic in an async function and run it using asyncio.run().

error ModuleNotFoundError: No module named 'libsql_experimental' ↓

cause The `libsql-experimental` package has not been installed in your current Python environment, or the Python interpreter running your script is not the one where the package was installed.

fix

Install the package using pip: pip install libsql-experimental. If you are using virtual environments, ensure your environment is activated before installation and when running your script. Verify the Python interpreter being used (e.g., which python and python -m pip install ...).

error pyo3_runtime.PanicException: not yet implemented (when inserting None values) ↓

cause This error indicates that the `libsql-experimental` library, at the specific version used, does not yet support inserting `None` (Python's `null`) directly as a parameter in `execute` or `executemany` statements, resulting in an unimplemented panic in the underlying Rust code.

fix

Instead of passing None directly, explicitly pass an empty string '' or a string representation of NULL if your schema allows it and the database interprets it correctly as a NULL value, or wait for a library update that implements this functionality.

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

breaking Building `libsql-experimental` in `musl`-based Linux environments (e.g., Alpine Linux) requires `gcc` or `build-base` to be installed. Without it, `cargo` may fail to find necessary shared libraries (e.g., `libgcc_s.so.1`) or encounter relocation errors, preventing package installation. ↓

fix Ensure `gcc` or a development package like `build-base` is installed in your `musl` environment. For Alpine Linux, run: `apk add build-base`.

Install compatibility stale last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - - -

3.10 slim (glibc) - - 0.00s 31M

3.11 alpine (musl) - - - -

3.11 slim (glibc) - - 0.00s 33M

3.12 alpine (musl) - - - -

3.12 slim (glibc) - - 0.00s 25M

3.13 alpine (musl) - - - -

3.13 slim (glibc) - - 0.00s 25M

3.9 alpine (musl) - - - -

3.9 slim (glibc) - - 0.00s 31M

Imports

libsql_experimental
wrong
```
import turso
```
correct
```
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

wrong

import sqlite3
conn = sqlite3.connect('libsql://...')

correct

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 stale last tested: 2026-05-12

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()