grafeo

library0.5.42pypypi✓ verified 83d ago

A high-performance, embeddable graph database with Python bindings. Current version 0.5.41, released 2026-04-24. Rapid release cadence, often multiple releases per week. Supports multiple query languages (GQL, Cypher, SPARQL, GraphQL, SQL/PGQ, Gremlin), hybrid graph+vector+text search, encryption at rest, and role-based access control.

database vector-search serialization auth-security aws

pip install grafeo

github ↗package ↗homepage ↗docs ↗

INSTALL

IMPORT

SIG · GRAFEO

grafeo

databasepythonv0.5.42

Install

1.9s avg

Import

—

Disk

27MB

Pass rate

4/ 10

Env Coverage4 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.5.42 · 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

musl

glibc

py 3.10

✕ build_error

py 3.11

✕ build_error

py 3.12

✓ —

✓ 1.8s

py 3.13

✓ —

✓ 1.9s

py 3.9

✕ build_error

27MB installed

● package 27MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

GrafeoDB

✓ from grafeo import GrafeoDB

✗ from grafeodb import GrafeoDB

The package is 'grafeo', not 'grafeodb'.

GrafeoSession

✓ from grafeo import GrafeoSession

QueryResult

✓ from grafeo import QueryResult

Creates an embedded graph database, opens a session, runs a Cypher query, prints results.

from grafeo import GrafeoDB db = GrafeoDB("mygraph.grafeo") session = db.session() result = session.execute("CREATE (a:Person {name: 'Alice'}) RETURN a") print(result.rows()) db.close()

grafeo --version

Debug

Known issues

breakingStarting from v0.5.35, QueryResult.rows is private; use rows() or into_rows() instead.

fix

Replace .rows with .rows() or .into_rows().

affects: >=0.5.35

breakingOn-disk storage format changed in v0.5.35 from bincode blobs to block-based sections. Databases created with 0.5.34 or earlier must be re-created.

fix

Export data from old database and import into new database.

affects: >=0.5.35

breakingQueryBuilder.param() now raises ValueError on unsupported types instead of silently dropping them (since v0.5.38).

fix

Ensure all parameter types are supported (strings, numbers, etc.).

affects: >=0.5.38

deprecatedFeature profiles 'embedded', 'browser', 'server', 'full' are deprecated in v0.5.35; use persona-based profiles: 'lpg', 'rdf', 'analytics', 'ai', 'edge', 'enterprise'.

fix

Switch to persona-based profiles when installing or building from source.

affects: >=0.5.35

gotchaWhen using encryption at rest (AES-256-GCM), the password or key must be provided at database creation time and cannot be changed later without re-encryption.

fix

Pass encryption config on first open; if re-creating, use compact() on the original first.

affects: >=0.5.39

gotchaHLC timestamps (Hybrid Logical Clock) introduced in v0.5.32 are mandatory for causal consistency. Sessions may fail if clocks are skewed beyond accepted drift.

fix

Ensure system clock is synchronized (e.g., NTP).

affects: >=0.5.32

gotchaVector search requires the 'ai' or 'analytics' profile. Plain 'lpg' or 'rdf' profiles may not include vector indexes.

fix

Install with correct profile: pip install grafeo[ai] or similar.

affects: >=0.5.35

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'grafeodb'

Wrong import; package name is 'grafeo' not 'grafeodb'.

fix

Install 'grafeo' and import as 'from grafeo import GrafeoDB'.

AttributeError: 'QueryResult' object has no attribute 'rows'

Attribute .rows is private since v0.5.35.

fix

Use .rows() or .into_rows() instead.

ValueError: unsupported type for parameter

QueryBuilder.param() rejects unsupported types since v0.5.38.

fix

Pass only str, int, float, bool, None, or bytes.

grafeo.exceptions.StorageError: database format is too old

Database created with pre-0.5.35 version.

fix

Re-create database from scratch or migrate via export/import.

Upgrade

Version history

0.5.42latest on PyPI · released May 4, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

49 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/GrafeoDB/grafeo ↗

packagehttps://pypi.org/project/grafeo/ ↗

homepagehttps://grafeo.dev ↗

docshttps://grafeo.dev/user-guide/ ↗