Install & Compatibility
Where this runs
tested against v0.11.3 · 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.920 runs
build_error
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 2.0s · import 0.217s · 39MB
37MB installed
● package 37MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Database
✓ from kuzu import Database
✗ import kuzu
db = kuzu.Database('path/to/db')
Connection
✓ from kuzu import Connection
QueryResult
✓ from kuzu import QueryResult
This quickstart demonstrates how to initialize a Kuzu database, define a schema with node and relationship tables, insert data, and execute Cypher queries using the Python API. It also shows how to retrieve results as a list of rows or a Pandas DataFrame. Remember to explicitly delete `Connection` and `Database` objects to ensure proper cleanup and data persistence, especially in scripts that exit immediately.
import kuzu
# Initialize a database and connection
db_path = 'my_graph_db'
db = kuzu.Database(db_path)
conn = kuzu.Connection(db)
# Define schema (Node Tables and Relationship Tables)
conn.execute("""
CREATE NODE TABLE User(name STRING, age INT64, PRIMARY KEY (name));
CREATE NODE TABLE City(name STRING, population INT64, PRIMARY KEY (name));
CREATE REL TABLE LivesIn(FROM User TO City, start_date DATE);
""")
# Insert data
conn.execute("INSERT INTO User VALUES ('Alice', 30), ('Bob', 25);")
conn.execute("INSERT INTO City VALUES ('New York', 8000000), ('London', 9000000);")
conn.execute("INSERT INTO LivesIn VALUES ('Alice', 'New York', DATE('2020-01-01'));")
conn.execute("INSERT INTO LivesIn VALUES ('Bob', 'London', DATE('2021-03-15'));")
# Query data
result = conn.execute("MATCH (u:User)-[l:LivesIn]->(c:City) RETURN u.name, c.name, l.start_date;")
# Fetch and print results
for row in result.get_as_list():
print(f"User: {row[0]}, City: {row[1]}, Lived Since: {row[2]}")
# Close the database connection (important to flush changes)
del conn
del db
# You can also fetch results as a Pandas DataFrame if pandas is installed
try:
import pandas as pd
db_df = kuzu.Database(db_path) # Re-open database
conn_df = kuzu.Connection(db_df)
df_result = conn_df.execute("MATCH (u:User) RETURN u.name, u.age;").get_as_df()
print("\nResults as DataFrame:")
print(df_result)
del conn_df
del db_df
except ImportError:
print("\nInstall pandas (pip install pandas) to see DataFrame output.")
kuzu --version
Debug
Known issues
breakingExtension management has changed significantly in v0.11.3. For versions prior to v0.11.3, you needed to set up a local extension server and manually `INSTALL` extensions (e.g., `algo`, `fts`, `json`, `vector`). In v0.11.3, these four common extensions are pre-installed and pre-loaded. For other extensions or prior Kuzu versions, a local extension server is still required.fixFor v0.11.3, commonly used extensions are bundled. For other extensions or older versions, set up a local extension server and use `INSTALL <EXTENSION_NAME> FROM 'http://localhost:8080/';` in your Cypher queries.
affects: < 0.11.3
gotchaThe KuzuDB project on GitHub (kuzudb/kuzu) has been marked as 'archived', and a note indicates Kuzu is 'working on something new'. While prior releases are stated to be usable without modification, this indicates a potential shift in the project's long-term direction or the primary repository for future development.fixMonitor the official KuzuDB website and GitHub organization for announcements regarding new repositories, project direction, or potential migration paths for future development. Back up your databases regularly.
affects: All versions
gotchaUsing Kuzu CLI to open a database created with the Python API (or vice-versa) can sometimes lead to 'Trying to read a database file with an unmatched version' errors due to versioning or internal format differences.fixEnsure that the Kuzu CLI and Python client versions are compatible, ideally identical. If encountering issues, try opening the database exclusively with the client (Python or CLI) that created it, or migrate data if a version mismatch is confirmed.
affects: All versions, especially when mixing client types.
gotchaIn Kuzu v0.10.0, a bug could lead to segmentation faults if `QueryResult` objects were garbage collected after their parent `Connection` or `Database` objects were closed, due to use-after-free in the underlying C++ code.fixExplicitly `del` all `QueryResult` objects (and any other child objects) before closing or deleting their parent `Connection` or `Database` objects. Calling `gc.collect()` immediately after deletion can also help force cleanup. This issue should be resolved in later versions (e.g., 0.11.x and above).
affects: 0.10.0 and potentially earlier
Upgrade
Version history
0.11.3latest on PyPI · released Oct 10, 2025
Audit
Dependencies
pandasoptionalCommonly used for converting query results to DataFrames via `get_as_df()` method.