Graphify-Labs/graphify · error · ImportError

falkordb SDK not installed. Run: pip install falkordb

Error message

falkordb SDK not installed. Run: pip install falkordb

What it means

Raised by graphify's FalkorDB exporter when the `falkordb` SDK cannot be imported. FalkorDB is a Redis-module-based graph database queried with Cypher over a graph key inside a Redis instance; the exporter imports the SDK lazily, mirroring the Neo4j path (MERGE upserts, optional auth) and reports the missing package with a pip hint.

Source

Thrown at graphify/exporters/graphdb.py:111

    identical to push_to_neo4j. Differences from the Neo4j path:
      - connects with FalkorDB(host, port, username, password) instead of a bolt
        driver; only the host/port are read from the URI, so the scheme is
        informational - "falkordb://localhost:6379", "redis://localhost:6379"
        and a bare "localhost:6379" are all equivalent (default port 6379).
      - a named graph is selected via db.select_graph(graph_name) (default
        "graphify"); FalkorDB keys each graph by name in the same instance.
      - queries run via graph.query(cypher, params) - there is no session object.
      - auth is optional (FalkorDB runs without credentials by default), so user
        and password may be None.
      - no APOC: the Neo4j path does not use APOC either, so nothing to port.

    Uses MERGE so re-running is safe - nodes and edges are upserted, not
    duplicated. Returns a dict with counts of nodes and edges pushed.
    """
    try:
        from falkordb import FalkorDB
    except ImportError as e:
        raise ImportError(
            "falkordb SDK not installed. Run: pip install falkordb"
        ) from e

    from urllib.parse import urlparse

    node_community = _node_community_map(communities) if communities else {}

    def _safe_rel(relation: str) -> str:
        return re.sub(r"[^A-Z0-9_]", "_", relation.upper().replace(" ", "_").replace("-", "_")) or "RELATED_TO"

    def _safe_label(label: str) -> str:
        """Sanitize a FalkorDB node label to prevent Cypher injection."""
        sanitized = re.sub(r"[^A-Za-z0-9_]", "", label)
        return sanitized if sanitized else "Entity"

    parsed = urlparse(uri if "://" in uri else f"redis://{uri}")
    # FalkorDB auth is optional. Only send credentials when a password is
    # provided; otherwise connect anonymously and ignore any bolt-style default

View on GitHub (pinned to 7fe58b0b0f)

Solutions

  1. pip install falkordb
  2. Verify in the same environment: `python -c "from falkordb import FalkorDB"`
  3. Then confirm the target Redis instance has the FalkorDB module loaded (connection errors are separate from this import error)

Example fix

# before
from graphify.exporters.graphdb import push_to_falkordb
push_to_falkordb(G, host="localhost", port=6379)  # ImportError

# after
pip install falkordb
push_to_falkordb(G, host="localhost", port=6379)
Defensive patterns

Strategy: validation

Validate before calling

import importlib.util

if importlib.util.find_spec("falkordb") is None:
    raise SystemExit("Install the FalkorDB SDK first: pip install falkordb")

from graphify.exporters.graphdb import push_to_falkordb
push_to_falkordb(G, host="localhost", port=6379)

Try / catch

try:
    push_to_falkordb(G, host=host, port=port)
except ImportError as e:
    if "falkordb" in str(e):
        log.warning("falkordb export skipped: %s", e)
    else:
        raise

Prevention

When it happens

Trigger: Calling the push-to-FalkorDB export function (e.g. `graphify export --falkordb ...`) where `from falkordb import FalkorDB` raises ImportError.

Common situations: Base graphify install without the graphdb extra; assuming the neo4j package also covers FalkorDB; running against a FalkorDB-capable Redis but forgetting the client SDK in the venv.

Related errors

AI-assisted analysis of Graphify-Labs/graphify@7fe58b0b0f (2026-08-14). Data as JSON: /api/errors/21f33e19df44ec0d. Report an issue: GitHub.