Turso Quickstart (Python)

In this Python quickstart we will learn how to:

Install the Turso package
Connect to a local or remote database
Execute a query using SQL
Sync changes to local database

Recommended: pyturso (Local / Embedded)

pyturso is the recommended package for local and embedded use cases. It is built on the Turso Database engine — a ground-up rewrite of SQLite with concurrent writes (MVCC) and async I/O. The API follows the standard Python sqlite3 interface, so it works as a drop-in replacement.

Install

uv add pyturso

Or with pip:

pip install pyturso

Connect

import turso

db = turso.connect("app.db")

In-memory databases are also supported:

db = turso.connect(":memory:")

Execute

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

for row in db.execute("SELECT * FROM users"):
    print(row)

Sync (push and pull)

If you need to sync your local database with Turso Cloud, use turso.sync:

import os
import turso.sync

db = turso.sync.connect(
    "app.db",
    remote_url=os.environ["TURSO_DATABASE_URL"],
    auth_token=os.environ["TURSO_AUTH_TOKEN"],
)

db.execute("INSERT INTO users (name) VALUES (?)", ("Bob",))
db.commit()

# Push local writes to Turso Cloud
db.push()

# Pull remote changes to local database
db.pull()

All reads and writes happen against the local database file — fast, offline-capable. push() sends your changes to the cloud. pull() brings remote changes down. See Turso Sync for details on conflict resolution, checkpointing, and more.

Remote Access (Over-the-Wire)

If your application needs to query a Turso Cloud database directly over the network (e.g., from a web server or serverless function), you can use the libsql package. It connects to your database via HTTP — no local file needed.

For most applications, we recommend running a local database with Turso Sync (turso.sync) instead — it gives you faster reads, offline support, and lower latency. Remote access is useful when you cannot store a local database file (e.g., stateless serverless environments).

Retrieve database credentials

You will need an existing database to continue. If you don’t have one, create one.Get the database URL:

turso db show --url <database-name>

Get the database authentication token:

turso db tokens create <database-name>

Assign credentials to the environment variables inside .env.

TURSO_DATABASE_URL=
TURSO_AUTH_TOKEN=

You will want to store these as environment variables.

Install

uv add libsql

Or with pip:

pip install libsql

Connect and query

import os
import libsql

conn = libsql.connect(
    database=os.environ["TURSO_DATABASE_URL"],
    auth_token=os.environ["TURSO_AUTH_TOKEN"],
)

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

Embedded Replicas (libsql)

The libsql package also supports Embedded Replicas — local reads from a file, with writes sent to the cloud primary and reflected back to the replica. Embedded Replicas are fully supported in production. For new projects that need sync, we recommend turso.sync instead: both reads and writes are local, and you sync explicitly with push() / pull(). See the reference for full documentation on Embedded Replicas, encryption, and periodic sync.

Turso Cloud

SDKs

CLI

API Reference

Integrations

Turso Quickstart (Python)

Recommended: pyturso (Local / Embedded)

Remote Access (Over-the-Wire)

Embedded Replicas (libsql)

​Recommended: pyturso (Local / Embedded)

​Remote Access (Over-the-Wire)

​Embedded Replicas (libsql)

Recommended: pyturso (Local / Embedded)

Remote Access (Over-the-Wire)

Embedded Replicas (libsql)