FrankenNetworkX: A Rust Port of NetworkX That Preserves Observable Behaviour

The Performance Gap FrankenNetworkX Targets

NetworkX is the standard Python graph library. It is accurate, comprehensive, and slow on anything beyond toy-sized data. Its pure-Python adjacency model, Python-level inner loops, and per-call dictionary bookkeeping turn graph analytics over even modest graphs, on the order of 100,000 to 1,000,000 nodes, into multi-minute operations. The GIL is held throughout.

Existing alternatives pay for speed with compatibility. They expose different APIs, change tie-break behaviour, lose attribute fidelity, or drop entire algorithm families. A user who migrates to one of them must rewrite call sites and accept that results may differ from what NetworkX produces.

FrankenNetworkX takes a different position. The README describes the design goal as treating NetworkX's observable behaviour as a hard constraint: graph mutation semantics, iteration order, tie-break choices, exception classes, error message wording, and serialization round-trip behaviour are all part of the contract. Where plain NetworkX raises TypeError for an unhashable key, FrankenNetworkX raises the same TypeError. Where NetworkX returns a generator, FrankenNetworkX returns a generator with the same repr, not a list.

Installing FrankenNetworkX

FrankenNetworkX is distributed on PyPI as the franken-networkx package. No Rust toolchain is required to install the prebuilt wheels:

pip install franken-networkx

Prebuilt ABI3 wheels are available for Linux (x86_64, aarch64, and musllinux), macOS (x86_64 and arm64), and Windows (x86_64) for Python 3.10 and later. The README states that source builds remain available for developers who need to modify Rust internals.

The pyproject.toml lists two runtime dependencies: networkx>=3.0 and numpy>=1.24. FrankenNetworkX imports NetworkX itself, which is the reference implementation it runs its conformance tests against. This means installing FrankenNetworkX also installs NetworkX, and both are available in the same environment.

The current version is v0.2.2, released on 2026-09-12. The Cargo.toml workspace version matches. Build profiles in the release configuration use thin LTO and a single codegen unit to allow cross-crate inlining across the fnx-classes, fnx-algorithms, and fnx-python crates.

Two Usage Modes: Standalone and Backend

FrankenNetworkX supports two usage modes. In standalone mode, the library is imported and called directly using the same API as NetworkX, with the same four core graph types: Graph, DiGraph, MultiGraph, and MultiDiGraph. The repository includes example scripts in examples/basic_usage.py and examples/social_network.py that demonstrate this path.

In backend mode, FrankenNetworkX registers itself as a NetworkX 3.0 backend. Existing code that imports NetworkX can dispatch supported calls into Rust without any call-site changes: once the backend is registered, NetworkX routes supported calls automatically. The example at examples/backend_mode.py shows this registration. The example at examples/benchmark_comparison.py compares the two modes against plain NetworkX on the same workload.

The backend dispatch surface covers 313 registered algorithms, listed in backend.py. Algorithms not in that set fall back to plain NetworkX. The coverage matrix under docs/ is regenerated on every quality run and checked for drift, so the boundary between dispatched and non-dispatched algorithms is tracked and documented rather than left to guesswork.

The four graph types in standalone mode match NetworkX's four core types exactly. The README states this is a deliberate constraint: the class and member signature gaps are measured in docs/coverage.md, and the classifier rejects shapes declared only through metadata.

The Conformance Testing Model

The claim of behavioural parity is enforced by tooling, not by assertion. The README describes four layers of conformance testing. The Python parity suite at tests/python/ contains approximately 1,100 files that compare fnx-vs-nx call by call across thousands of fixtures, covering iteration order, exception class, and error wording. The README reports 68,318 passed and 0 failed on 2026-09-24.

The second layer is NetworkX's own test suite run with FrankenNetworkX as the backend. The README states 6,815 tests pass and 0 fail against the 6,816 that pass on plain NetworkX 3.6.1. One test is skipped in addition to the plain NetworkX skip count of 78.

The third layer is a Rust differential conformance harness. The fourth is a set of five generated audit ledgers: a coverage matrix, a raw-vs-public surface comparison, a delegation tracker, an upstream divergence record, and an API ergonomics report.

The CGSE (13-variant TieBreakPolicy) gives each algorithm execution a Blake3-based complexity witness, producing a length-prefixed decision-path ledger. This means behavioral parity can be regression-locked, not just spot-checked on a given day.

What the Coverage Matrix Documents

FrankenNetworkX does not claim complete algorithm coverage. The README is explicit: the live FeatureUniverse records paths as present, partial, missing, not applicable, or with a reasoned exclusion. The coverage matrix achieves 4,129 strictly present paths out of 4,129 applicable paths in the declared import and signature surface for NetworkX 3.6.1, but this covers declared exports, not every algorithm implementation.

The docs/coverage.md file in the repository documents which algorithms have partial coverage. A partial algorithm is one where some inputs or code paths are handled in Rust and others fall back to Python. This distinction matters for performance-sensitive workloads: an algorithm listed as partial may still execute entirely in Python for certain inputs.

The 33 cargo-fuzz binaries across parsers and algorithm families provide coverage for edge cases that are difficult to reach with example-based tests. The fuzz smoke run is part of the DSR quality gate, which also runs format checks, clippy with -D warnings, Rust unit tests across all 11 crates, and the full Python parity suite.

Limitations and When FrankenNetworkX Is the Wrong Choice

FrankenNetworkX is at version 0.2.2, in beta. The pyproject.toml classifies it as Development Status 4 (Beta). API stability is not guaranteed across minor versions, and the README notes that the FeatureUniverse coverage is the living record, not a completed claim.

The 313 backend-registered algorithms cover a substantial but incomplete portion of the NetworkX surface. A workflow that relies heavily on algorithms outside that set will see no performance benefit in backend mode, because those calls dispatch to plain NetworkX.

The library requires networkx>=3.0 as a runtime dependency, so it does not replace NetworkX but supplements it. Projects pinned to NetworkX 2.x cannot use FrankenNetworkX without first upgrading their NetworkX dependency.

For graph analytics that run on graphs small enough to complete in seconds in plain NetworkX, FrankenNetworkX adds a dependency and a Rust-Python FFI boundary without a meaningful throughput gain. The overhead of the FFI layer is non-trivial for short-running algorithms on small graphs, as the comparison table in the README discusses.

Editorial conclusion

FrankenNetworkX is the right choice for Python data scientists and graph engineers who need faster graph analytics on graphs of 100,000 nodes or more and cannot afford to rewrite call sites or accept divergent iteration order. The conformance test suite and the NetworkX-as-backend mode are the two things to verify before adopting it: run NetworkX's own test suite with fnx as the backend against your specific algorithms and confirm that all 313 registered algorithms cover your workload. The library is at v0.2.2, released 2026-09-12, under an MIT licence. Gaps are measured in docs/coverage.md; partial-coverage algorithms are documented rather than silently skipped.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes