Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.turso.tech/llms.txt

Use this file to discover all available pages before exploring further.

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
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.
1

Install

uv add pyturso
Or with pip:
pip install pyturso
2

Connect

import turso

db = turso.connect("app.db")
In-memory databases are also supported:
db = turso.connect(":memory:")
3

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

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).
1

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.
2

Install

uv add libsql
Or with pip:
pip install libsql
3

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)

​
Legacy: libsql (Embedded Replicas)

The libsql package also supports embedded replicas, where reads are local but writes go to the remote database. For true local-first writes with push/pull sync, use turso.sync instead. See the reference for full documentation on embedded replicas, encryption, and periodic sync.