Skip to content
GraphForge

Installation

GraphForge ships as thin native bindings over a Rust core (Python via maturin; Node via N-API). Install the published packages for normal use; build from source on main when developing the engine or bindings.

Prefer an editor workflow? The optional GraphForge VS Code extension detects Node- and Python-first workspaces, helps configure the appropriate native binding, and uses the same Rust-owned engine described below.

Name collision: PyPI also lists an unrelated pure-Python package named graphforge at 0.4.0 (~279 KB). Current CurateLabs GraphForge releases are native wheels (Rust .so / .node) on PyPI and npm. Install by package name to receive the current release.

Python package

Section titled “Python package”

Requirements: Python 3.10 or newer (3.10–3.14 tested in CI).

pip

Terminal window
pip install graphforge

uv (recommended)

Terminal window
uv add graphforge

Verify

Section titled “Verify”
import graphforge
print(graphforge.__version__)

Optional dependencies

Section titled “Optional dependencies”
Terminal window
# Polars convenience wrapper around Arrow results
pip install "graphforge[polars]"

Results are Apache Arrow tables. Convert with table.to_pandas(), pl.from_arrow(table), or table.to_pylist() as needed. Graph algorithms run in the native Rust engine; NetworkX and igraph are development-only parity oracles, not runtime backends.

Python installs typically also pull PyArrow as a separate runtime dependency (not bundled inside the graphforge wheel). See Install footprint for approximate sizes.

Node package (@curatelabs/graphforge)

Section titled “Node package (@curatelabs/graphforge)”

Requirements: a current Node.js LTS (CI covers the binding’s supported targets).

npm

Terminal window
npm install @curatelabs/graphforge

pnpm

Terminal window
pnpm add @curatelabs/graphforge
import { GraphForge } from "@curatelabs/graphforge";

For local engine work, install from a release build or path dependency in this repository (see Install from source).

Install footprint

Section titled “Install footprint”

Approximate download and on-disk sizes for operators sizing CI images, laptops, and air-gapped mirrors. These are not scale-limits query/bench results.

Surface Packed / download Installed / unpacked
Python graphforge ~42 MB wheel ~121 MB (mostly _graphforge_rs.abi3.so)
Node @curatelabs/graphforge ~44 MB npm pack ~128 MB (mostly .node ≈ 121 MB)
PyArrow (Python dep, e.g. 21.0.0) ~31 MB wheel ~108 MB

Caveats

  • Measured on local macOS arm64 (darwin-arm64) release builds of 0.5.1. Other OS/arch combinations will differ.
  • Almost all of the GraphForge footprint is the Rust native binary; the thin Python/JS wrappers are negligible by comparison.
  • PyArrow is separate — it is not inside the graphforge wheel. Budget it only for Python environments that install that dependency.
  • Do not confuse these sizes with PyPI graphforge 0.4.0 (unrelated pure-Python package, ~279 KB).

Install from source (main)

Section titled “Install from source (main)”

Building from source requires a Python environment and the Rust toolchain.

Requirements

Section titled “Requirements”
  • Python 3.10 or newer
  • Rust stable toolchain (rustup)
  • uv
  • maturin (Python/Rust build bridge)

Setup

Section titled “Setup”
Terminal window
# 1. Install Rust (if not already installed)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup update stable


# 2. Clone
git clone https://github.com/CurateLabs/graphforge.git
cd graphforge


# 3. Install Python dev dependencies
uv sync --dev


# 4. Build and install the Rust extension in development mode
maturin develop --release -m crates/graphforge-bindings-py/Cargo.toml


# 5. Verify
python -c "import graphforge; print(graphforge.__version__)"

Run checks

Section titled “Run checks”
Terminal window
# Rust: unit + integration tests across all crates
cargo test --workspace


# Rust: lint
cargo clippy --workspace -- -D warnings


# Full pre-push suite
make pre-push

Next steps

Section titled “Next steps”