{"id":106,"library":"libsql-experimental","title":"Turso Python SDK","description":"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').","status":"active","version":"0.0.49","language":"python","source_language":"en","source_url":"https://github.com/tursodatabase/libsql-experimental-python","tags":["turso","libsql","sqlite","database","embedded-replica","python","dbapi2"],"install":[{"cmd":"pip install libsql-experimental","lang":"bash","label":"Python (PyPI)"}],"dependencies":[],"imports":[{"note":"The package is named libsql-experimental on PyPI and imported as libsql_experimental. There is no 'turso' Python module.","wrong":"import turso","symbol":"libsql_experimental","correct":"import libsql_experimental as libsql"},{"note":"sqlite3 cannot connect to Turso remote URLs. Use libsql_experimental.connect() with sync_url and auth_token for remote Turso databases.","wrong":"import sqlite3\nconn = sqlite3.connect('libsql://...')","symbol":"connect","correct":"import libsql_experimental as libsql\nconn = libsql.connect('mydb.db', sync_url='libsql://...', auth_token='...')"}],"quickstart":{"code":"import os\nimport libsql_experimental as libsql\n\nurl = os.environ.get('TURSO_DATABASE_URL', '')\ntoken = os.environ.get('TURSO_AUTH_TOKEN', '')\n\n# Embedded replica with local file + remote sync\nconn = libsql.connect('local.db', sync_url=url, auth_token=token)\nconn.sync()\n\nconn.execute('CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)')\nconn.execute('INSERT INTO users (name) VALUES (?)', ('Alice',))\nconn.commit()\n\nrows = conn.execute('SELECT * FROM users').fetchall()\nfor row in rows:\n    print(row)\n\nconn.sync()","lang":"python","description":"Connect to a Turso database using an embedded replica pattern with local SQLite file and remote sync."},"warnings":[{"fix":"pip install libsql-experimental","message":"The package name is libsql-experimental, not turso or libsql. `pip install turso` will install a different unrelated package or fail.","severity":"gotcha","affected_versions":"all"},{"fix":"Call conn.sync() after writes and before reads that need fresh remote data.","message":"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.","severity":"gotcha","affected_versions":"all"},{"fix":"Always call conn.commit() after write operations, or use conn.executescript() which auto-commits.","message":"conn.commit() is required after INSERT/UPDATE/DELETE. Auto-commit is not enabled by default, matching dbapi2 behavior.","severity":"gotcha","affected_versions":"all"},{"fix":"Provide a valid local file path: libsql.connect('local.db', sync_url=url, auth_token=token)","message":"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:'.","severity":"gotcha","affected_versions":"all"},{"fix":"Remote only: libsql.connect(url, auth_token=token). Embedded replica: libsql.connect('local.db', sync_url=url, auth_token=token).","message":"For remote-only connections (no local replica), pass the libsql:// URL as the first argument without sync_url. Mixing them up causes connection errors.","severity":"gotcha","affected_versions":"all"},{"fix":"Pin your version in production: libsql-experimental==0.0.49","message":"The package is marked 'experimental'. API surface may change between minor releases without deprecation warnings.","severity":"deprecated","affected_versions":"all"},{"fix":"Ensure `gcc` or a development package like `build-base` is installed in your `musl` environment. For Alpine Linux, run: `apk add build-base`.","message":"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.","severity":"breaking","affected_versions":"all"}],"env_vars":[{"name":"TURSO_DATABASE_URL","required":true,"description":"The libsql:// URL for your Turso database."},{"name":"TURSO_AUTH_TOKEN","required":true,"description":"Auth token for authenticating with Turso. Generated via `turso db tokens create`."}],"last_verified":"2026-05-12T08:09:14.698Z","next_check":"2026-06-17T00:00:00.000Z","problems":[{"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.","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.","error":"error: subprocess-exited-with-error × Building wheel for libsql-experimental (pyproject.toml) did not run successfully."},{"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()`.","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.","error":"pyo3_runtime.PanicException: there is no reactor running, must be called from the context of a Tokio 1.x runtime"},{"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 ...`).","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.","error":"ModuleNotFoundError: No module named 'libsql_experimental'"},{"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.","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.","error":"pyo3_runtime.PanicException: not yet implemented (when inserting None values)"}],"ecosystem":"pypi","meta_description":null,"install_score":30,"install_tag":"stale","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0,"mem_mb":0,"disk_size":"31M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0,"mem_mb":0,"disk_size":"33M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0,"mem_mb":0,"disk_size":"25M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0,"mem_mb":0,"disk_size":"25M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0,"mem_mb":0,"disk_size":"31M"}]},"quickstart_checks":{"last_tested":"2026-05-12","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}