Install & Compatibility
Where this runs
tested against v4.2.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.376s · 20.8MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.0s · import 0.352s · 21MB
19MB installed
● package 19MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Database
✓ from sqlite_utils import Database
This quickstart demonstrates how to create a Database object, insert data into a table (which is automatically created if it doesn't exist), and then query and update data. It shows both in-memory and file-based database creation.
from sqlite_utils import Database
# Create an in-memory database
db = Database(memory=True)
# Or create a file-based database
# db = Database('my_data.db')
# Insert data into a table, creating it if it doesn't exist
db["dogs"].insert_all(
[
{"id": 1, "name": "Cleo", "age": 4},
{"id": 2, "name": "Pancakes", "age": 2}
],
pk="id"
)
# Query data
for row in db.query("select * from dogs where age > ?", [3]):
print(row)
# Access table objects and perform operations
dogs_table = db["dogs"]
print(f"Total dogs: {dogs_table.count}")
dogs_table.update(1, {"age": 5})
for row in dogs_table.rows: # Iterate through all rows
print(row)
sqlite-utils --version
Debug
Known issues
breakingThe `db.table(table_name)` method now exclusively works with tables. To access SQL views, you must use `db.view(view_name)` instead. This change improves type hinting capabilities for tables vs views.fixUpdate calls from `db.table()` to `db.view()` for SQL views.
affects: 4.0a1 and later
breakingUpsert operations (`.upsert()` and `.upsert_all()`) now utilize SQLite's `INSERT ... ON CONFLICT SET` syntax on SQLite versions newer than 3.23.1. Previously, it used `INSERT OR IGNORE` followed by an `UPDATE`. While largely functionally equivalent, applications depending on the exact old behavior might see minor differences.fixIf the old behavior is critical, pass `use_old_upsert=True` to the `Database()` constructor. Otherwise, ensure your code is compatible with the new upsert mechanism.
affects: 4.0a0 and later (for SQLite versions > 3.23.1)
breakingsqlite-utils now requires Python 3.10 or higher. Older Python versions are no longer supported.fixUpgrade your Python environment to 3.10 or a newer compatible version.
affects: 3.39 and later
breakingThe default floating point column type has been changed from `FLOAT` to `REAL`, which is the correct SQLite type for floating-point values. This primarily affects auto-detected column types when inserting data.fixNo direct fix needed unless explicit type declarations are required, in which case specify column types during table creation or insertion.
affects: 4.0a1 and later
gotchaForeign key creation no longer directly manipulates the `sqlite_master` table using `PRAGMA writable_schema = 1`. Instead, it uses a table transformation mechanism. Code that relied on directly writing to `sqlite_master` for foreign key management may break or behave unexpectedly.fixUse the `table.transform()` method with `foreign_keys=` or `add_foreign_keys=` parameters, or `db['table'].add_foreign_key()` instead of direct schema manipulation.
affects: 3.35 and later
Errors
Common errors & fixes
sqlite-utils command not found
The `sqlite-utils` command-line tool is not installed or its installation directory is not in your system's PATH.
fixpip install sqlite-utils
ModuleNotFoundError: No module named 'sqlite_utils'
The `sqlite-utils` Python package is not installed in your current Python environment.
fixpip install sqlite-utils
sqlite3.OperationalError: no such table: mytable
You are attempting to query or interact with a table name that does not exist in the connected SQLite database.
fixVerify the table name's spelling, or ensure the table is created before interaction, e.g., by inserting data with `db["mytable"].insert(...)` which creates it if it doesn't exist.
sqlite3.IntegrityError: UNIQUE constraint failed: mytable.mycolumn
You are attempting to insert a row that violates a UNIQUE constraint defined on one of the table's columns.
fixProvide unique data, or use `db["mytable"].insert(data, replace=True)` or `db["mytable"].upsert(data, ["mycolumn"])` to handle duplicates.
Upgrade
Version history
4.2.1latest on PyPI · released Aug 13, 2026
Audit
Dependencies
pythonrequiredsqlite-utils 3.39 and later requires Python 3.10 or higher.