FrankenNetworkX: A Rust Port of NetworkX That Treats Observable Behavior as a Contract

The Problem: NetworkX's Pure-Python Slowness and the Cost of Alternatives

NetworkX is the standard Python graph library, but its pure-Python adjacency storage and Python-level inner loops make graph analytics over 100,000 to a million nodes take minutes. The README points out that most alternatives pay for speed with incompatibility: they change the API, lose attribute fidelity, or drop algorithm families. FrankenNetworkX targets that gap by promising a drop-in surface where observable behavior is a hard constraint. That includes iteration order, tie-break choices, exception classes, and even error message wording. The intended user is someone who has NetworkX code and wants it faster without rewriting calls or accepting subtle behavioral drift.

How It Works: Rust Core, Deterministic IndexMap, and GIL Release

FrankenNetworkX is a Rust 2024 port with `#![forbid(unsafe_code)]`, meaning it avoids unsafe Rust entirely. The core graph types are Graph, DiGraph, MultiGraph, and MultiDiGraph, matching NetworkX. Adjacency storage uses a deterministic IndexMap that preserves insertion order, which is critical for matching NetworkX's dict-based iteration order. The library releases the GIL on heavy work through hundreds of `py.allow_threads(...)` sites, which is a significant departure from pure-Python NetworkX. The README claims this allows parallel execution of independent graph operations. The design rejects both subclassing and wrapping approaches because they fail to move the cost or lose fidelity. Instead, it ports algorithms directly into Rust while keeping the Python-facing API.

Getting It Running: Pip Install and Backend Integration

Installation is straightforward: `pip install franken-networkx`. No Rust toolchain is required because pre-built wheels are provided for Linux, macOS, and Windows, supporting Python 3.10+ with ABI3. You can use it as a standalone library with the familiar NetworkX API, or wire it in as a `networkx>=3.0` backend so supported calls dispatch into Rust without changing call sites. The README mentions that 316 algorithms are registered in `backend.py` for backend dispatch. That means you can set it as a NetworkX backend and existing code will route to Rust automatically, but only for those 316 algorithms. Check the repository's documentation for the exact configuration for backend setup.

The Conformance Machinery: Parity Tests, Audit Ledgers, and CGSE Receipts

The project enforces behavioral parity through tooling, not goodwill. There is a 377-file Python parity test suite that compares fnx-vs-nx call by call across thousands of fixtures, including iteration order, exception class, and error wording. Additionally, five auto-generated audit ledgers under `docs/` fail CI if the public symbol surface drifts. The CGSE is a 13-variant TieBreakPolicy that explicitly handles tie-break determinism. Every algorithm execution produces a length-prefixed Blake3 decision-path ledger, giving a reproducible receipt for each call. This is a rigorous approach to regression-locking behavior, but it also means the system is complex. The CI gates, labeled G0 through G8, include docs freshness, formatting, clippy, Rust tests, Python parity, end-to-end tests, examples, conformance, performance SLO, UBS, fuzz smoke, and RaptorQ scrub. That is a heavy pipeline, which could slow development but also ensures high confidence.

Coverage Gaps: 82.3% Strictly Present, 700 Partial, 30 Missing

The README is explicit that this is not a complete drop-in replacement. Against the pinned NetworkX 3.6.1 FeatureUniverse, FrankenNetworkX has 3,399 strictly present paths out of 4,129 applicable, which is 82.3%. Another 700 are partial, and 30 are missing. That means if your code uses a function that is partial or missing, you might get a different behavior or an error. The project maintains a live FeatureUniverse record that distinguishes present, partial, missing, n/a, and reasoned exclusions. This is honest but also a practical limitation. For a team evaluating adoption, the first step is to check which of your called functions fall into the partial or missing categories. The README does not list which specific functions are missing, so you would need to consult `docs/coverage.md` in the repository.

Durability and Fuzzing: RaptorQ Sidecars and 33 Fuzz Binaries

A distinctive feature is the RaptorQ-backed durability. The project generates erasure-coded sidecars for conformance artifacts, with decode-proof receipts. This means that if you need to prove that a given graph operation produced a specific result, you have a cryptographic receipt. The README also mentions 33 cargo-fuzz binaries covering parsers and algorithm families, which suggests a strong focus on robustness against malformed inputs. It is not clear if this durability applies to user data or only to the project's internal test artifacts. That is a gap in the documentation, and potential adopters should clarify this before relying on it for production data persistence.

Alternatives and Why They Differ

The README compares FrankenNetworkX to several alternatives. igraph uses integer node IDs and has a different API, so it is not a drop-in. graph-tool is very fast but requires a custom build pipeline and has no PyPI wheel. rustworkx has a Rust core but is intentionally not a drop-in replacement, using integer IDs and an explicit conversion API. graspologic, networkx-cuda, and cugraph offer GPU acceleration but have varying algorithm coverage and often partial nx compatibility. The key difference is that FrankenNetworkX is the only one that treats tie-break parity and iteration order as part of the contract. If you need exact behavioral equivalence, it is the only option among these. But if you can tolerate API changes or integer node IDs, rustworkx or igraph might be simpler and more mature. The README's comparison is useful.

Maintenance and License Considerations

The license is listed as NOASSERTION, which is unusual. That means the repository does not declare a standard license, and you should consult the LICENSE file in the repository before using it in a commercial product. The README links to a LICENSE file but does not specify the terms. The project is not archived, and the last push was June 2026, with a recent release v0.2.0 on the same day. That suggests active development, but the maintenance cost is high due to the extensive CI pipeline and the need to track NetworkX updates. Since the project pins to NetworkX 3.6.1, any future NetworkX release could introduce drift, and the project would need to update its FeatureUniverse and parity tests. Upgrading FrankenNetworkX itself might also require re-running the full CI suite, which could be time-consuming. The README does not provide upgrade guides or migration notes, so plan for a learning curve when integrating new versions.

Editorial conclusion

Adopt FrankenNetworkX if you need NetworkX's API and behavior but are bottlenecked by pure-Python performance on graphs in the 10^5 to 10^6 node range, and you are willing to verify that your specific algorithm calls are within the 82.3% strictly present surface. Do not adopt it if you require full NetworkX coverage today, or if your workflows depend on the 30 missing paths or the 700 partial ones. Before adoption, run the Python parity suite against your own fixtures, check the coverage matrix in docs/coverage.md for every function you call, and confirm that the RaptorQ sidecar and CGSE ledger overhead is acceptable for your durability needs. The project is not archived, but the last push is June 2026, so verify the commit history for ongoing maintenance.

Frequently asked questions

Official sources

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