Install & Compatibility
Where this runs
tested against v1.6.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.920 runs
installs and imports cleanly · install 0.0s · import 0.489s · 23.8MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 2.2s · import 0.438s · 24MB
22MB installed
● package 22MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
FalkorDB
✓ from falkordb import FalkorDB
FalkorDB (async)
✓ from falkordb.asyncio import FalkorDB
Use this for asynchronous operations.
This quickstart demonstrates how to connect to a running FalkorDB instance, select or create a graph, insert data using Cypher queries, and retrieve results. It's crucial to have a FalkorDB server running (e.g., via Docker) before executing this code.
import os
from falkordb import FalkorDB
# Ensure FalkorDB server is running, e.g., via Docker:
# docker run -p 6379:6379 -p 3000:3000 -it --rm -v ./data:/var/lib/falkordb/data falkordb/falkordb
# Connect to FalkorDB (default host/port)
db = FalkorDB(host=os.environ.get('FALKORDB_HOST', 'localhost'), port=int(os.environ.get('FALKORDB_PORT', 6379)))
# Select a graph (or create if it doesn't exist)
g = db.select_graph('social')
# Create some data
create_query = """
CREATE (alice:User {id: 1, name: 'Alice', email: 'alice@example.com'})
CREATE (bob:User {id: 2, name: 'Bob', email: 'bob@example.com'})
CREATE (alice)-[:FRIENDS_WITH {since: 2020}]->(bob)
"""
g.query(create_query)
# Query the data
query = """
MATCH (u1:User)-[f:FRIENDS_WITH]->(u2:User)
RETURN u1.name, u2.name, f.since
"""
result = g.query(query)
# Print results
for record in result.result_set:
print(f"{record[0]} is friends with {record[1]} since {record[2]}")
# Close the connection (important for resource management)
db.close()
Debug
Known issues
breakingFalkorDB Python client v1.4.0 and later require Python 3.10 or higher. Older Python versions are no longer supported.fixUpgrade your Python environment to 3.10 or later.
affects: >=1.4.0
gotchaThe FalkorDB server itself requires Redis 7.4 or newer for optimal compatibility and latest features. While the Python client's `redis-py` dependency might be met with older Redis versions (e.g., Redis 7.1), using an outdated Redis server with FalkorDB can lead to unexpected behavior or missing functionality.fixEnsure your FalkorDB server is running on a Redis instance that is version 7.4 or higher, ideally Redis 8.x for the latest FalkorDB releases.
affects: All versions
gotchaExplicitly close FalkorDB connections when they are no longer needed using `db.close()` or `await db.aclose()` for async clients. This prevents resource leaks and ensures proper cleanup, especially in long-running applications or when managing connection pools.fixCall `db.close()` or `await db.aclose()` after completing your database operations.
affects: All versions (explicit methods added in v1.6.0)
gotchaFalkorDB's `LIMIT` clause does not affect eager operations like `CREATE`, `SET`, `DELETE`, `MERGE`, and projections with aggregate functions. For example, `UNWIND [1,2,3] AS value CREATE (a {property: value}) RETURN a LIMIT 1` will create three nodes but only return one.fixBe aware of this limitation when writing Cypher queries involving eager operations and `LIMIT`. Structure your queries to apply `LIMIT` after the eager operation has completed its full scope, if possible, or filter results at the client side if the server behavior is not desired.
affects: All versions
gotchaIn Cypher queries, if a relationship in a `MATCH` pattern is not explicitly referenced elsewhere in the query, FalkorDB may only verify the existence of at least one matching relationship rather than operating on every single matching one. This can lead to incorrect counts or unexpected results in certain `COUNT()` scenarios.fixTo ensure operations consider all matching relationships, explicitly refer to the relationship's alias in the query (e.g., `MATCH (a)-[e]->(b) WHERE ID(e) >= 0 RETURN COUNT(b)` or `MATCH (a)-[e]->(b) RETURN COUNT(b), e.dummyval`).
affects: All versions
Errors
Common errors & fixes
RedisLiteServerStartError: The redis-server process failed to start.
This error often occurs during development installs of `falkordblite` because the `redis-server` or `falkordb.so` binaries are not automatically copied to the `redislite/bin/` directory or lack execute permissions after an editable install.
fixFor development installations, ensure you explicitly build the project before installing in editable mode: `python setup.py build` followed by `pip install -e .`. For production, `pip install falkordblite` handles this automatically.
Library not loaded: /opt/homebrew/opt/libomp/lib/libomp.dylib
On macOS, the `falkordb` module, particularly when used via `falkordblite`, requires the OpenMP runtime library (`libomp`), which might not be installed by default.
fixInstall the OpenMP library using Homebrew: `brew install libomp`.
t: expected label (Cypher Query Syntax Error)
This FalkorDB Cypher query error indicates a syntax mismatch where a parameter is used immediately after a colon (`:`) in a context where a node label is strictly required by the parser.
fixEnsure that node labels are explicitly provided in your Cypher query, especially in `MATCH` patterns. Parameters should be bound to properties (e.g., `MATCH (n {id: $param_id})`) rather than directly as labels (e.g., avoid `MATCH (n:$param_label)`). from falkordb import FalkorDB (when using falkordblite)
Developers might mistakenly use the `falkordb` client's top-level import when they have installed `falkordblite` and intend to use its embedded server functionality, which requires a specific import path for its client.
fixIf you are using `falkordblite` to manage an embedded FalkorDB instance, import the client from its specific `redislite` path: `from redislite.falkordb_client import FalkorDB`.
Upgrade
Version history
1.6.1latest on PyPI · released Apr 28, 2026
Audit
Dependencies
pythonrequiredRequires Python 3.10 or higher.
redisrequiredThe falkordb client wraps redis-py for connection management. The client requires `redis>=7.1.0,<8.0.0` for its internal operations.