Skip to content

Install

NamiDB ships as a Python wheel, a server container image, prebuilt binaries and source. They are all the same engine; install the one that matches how you want to run it.

You want to…Install
Use the graph from Python code, notebooks or testsPython wheel
Run a server other processes connect to over HTTP or BoltDocker image or server binary
Run one-off queries, backups and vault imports from a shellnamidb CLI
Give an AI agent read access to a graphnamidb-mcp
Embed the engine in a Rust programRust crates

Python

Terminal window
pip install namidb
  • Python 3.9 or newer. pyarrow >= 14 is installed as a dependency.
  • Optional DataFrame extras: pip install 'namidb[pandas]' (pandas ≥ 2.0) and pip install 'namidb[polars]' (polars ≥ 0.20).
  • Prebuilt abi3 wheels exist for Linux x86_64 and aarch64, macOS arm64 and x86_64, and Windows x86_64. Other platforms build from the source distribution, which needs a Rust toolchain.
  • The wheels include the persistent vector and full-text indexes, so CREATE VECTOR INDEX and CREATE FULLTEXT INDEX work out of the box.

Check the install:

Terminal window
python -c "import namidb; print(namidb.__version__)"
# 3.3.0

Next: Embedded Python and the Python API reference.

Docker

The official namidb-server image is multi-arch (linux/amd64 and linux/arm64) and is built with vector and full-text search enabled.

RegistryImage
Docker Hubnamidb/namidb-server
GitHub Container Registryghcr.io/namidb/namidb-server

Each release is tagged X.Y.Z, X.Y, X and latest. Pin an exact version in production:

Terminal window
docker pull namidb/namidb-server:3.3.0

Run it with a named volume for a durable local store. The server refuses to start without an auth source, so pass a token:

Terminal window
export NAMIDB_AUTH_TOKEN="$(openssl rand -hex 32)"
docker run --rm -p 127.0.0.1:8080:8080 \
-v namidb-data:/var/lib/namidb \
-e NAMIDB_AUTH_TOKEN \
namidb/namidb-server:3.3.0 \
--store "file:///var/lib/namidb?ns=prod"
Terminal window
curl -s localhost:8080/v0/health
# {"status":"ok","namespace":"prod","manifest_version":0,"epoch":0,"writer":"ok",...}

What the image sets up:

  • The process runs as a non-root user (uid/gid 65532). /var/lib/namidb is pre-created and owned by that user, so a fresh named volume mounted there just works. A bind mount needs chown -R 65532:65532 <dir> on the host first.
  • NAMIDB_LISTEN=0.0.0.0:8080, NAMIDB_SPOOL_DIR=/var/tmp/namidb-spool, RUST_LOG=info, and bounded glibc allocator arenas (MALLOC_ARENA_MAX=2).
  • A built-in HEALTHCHECK that probes /v0/livez. It follows NAMIDB_LISTEN and switches to HTTPS when NAMIDB_TLS_CERT or NAMIDB_TLS_KEY is set; if you change the listen address or TLS with command-line flags instead, set the same values as environment variables so the probe sees them.

For a server backed by an S3-compatible bucket, see Docker + MinIO.

Release binaries

Each GitHub release ships prebuilt archives with SHA-256 checksums:

ArchiveContainsBuilt with
namidb-server-v3.3.0-<target>namidb-servervector-index, text-index
namidb-v3.3.0-<target>namidb (CLI) and namidb-mcpno optional features

Targets: x86_64-unknown-linux-gnu, aarch64-unknown-linux-gnu, aarch64-apple-darwin (.tar.gz) and x86_64-pc-windows-msvc (.zip). Linux archives are built on Ubuntu 22.04 and need glibc 2.35 or newer; use the container image or build from source for older systems.

Terminal window
TARGET=x86_64-unknown-linux-gnu # or aarch64-unknown-linux-gnu, aarch64-apple-darwin
BASE=https://github.com/namidb/namidb/releases/download/v3.3.0
curl -fsSLO "$BASE/namidb-server-v3.3.0-$TARGET.tar.gz"
curl -fsSLO "$BASE/namidb-server-v3.3.0-$TARGET.sha256"
sha256sum -c "namidb-server-v3.3.0-$TARGET.sha256"
tar xzf "namidb-server-v3.3.0-$TARGET.tar.gz"
./namidb-server --version
# namidb-server 3.3.0

The CLI archive works the same way and unpacks namidb and namidb-mcp:

Terminal window
./namidb --version # namidb 3.3.0
./namidb-mcp --version # namidb-mcp 3.3.0

From source

Requires Rust 1.85 or newer.

Terminal window
git clone https://github.com/namidb/namidb
cd namidb
git checkout v3.3.0
Terminal window
# Same feature set as the official image and release binary:
cargo install --locked --path crates/namidb-server --features vector-index,text-index
# Add OIDC/JWT and the external policy hook:
cargo install --locked --path crates/namidb-server --features vector-index,text-index,jwt,pdp

A plain cargo install without features gives a smaller binary that rejects CREATE VECTOR INDEX / CREATE FULLTEXT INDEX with HTTP 400.

Server featureEnables
vector-indexCREATE VECTOR INDEX, DROP VECTOR INDEX, and index-backed vector search
text-indexCREATE FULLTEXT INDEX, DROP INDEX, and index-backed BM25
jwt--jwt-* flags: OIDC / JWT bearer validation against a JWKS
pdp--pdp-url: an OPA-style external policy decision point

Next steps