franken_networkx

What FrankenNetworkX is

FrankenNetworkX is a Rust-backed NetworkX-compatible graph library with a measured, incomplete drop-in surface. You use it as a standalone library with the familiar NetworkX API, or wire it in as a networkx backend of version 3.0 or later so supported calls dispatch into Rust without call-site changes. Installation is a pip install, and no Rust toolchain is required because pre-built wheels are provided for Linux, macOS, and Windows on Python 3.10 and later with the ABI3 stable ABI. The problem it addresses is that NetworkX, the canonical Python graph library, is rich and correct but slow on graphs that are not toy-sized, because its pure-Python adjacency and per-call dict bookkeeping turn analytics over modest graphs into multi-minute affairs. Most faster alternatives pay for speed in compatibility by exposing a different API, changing tie-break behavior, losing attribute fidelity, or dropping algorithm families. FrankenNetworkX instead treats observable behavior as a hard constraint, so graph mutation semantics, iteration order, tie-break choices, exception classes, error message wording, and serialization round-trip behavior are all part of the contract it enforces. That stance is what separates it from a mere speed rewrite, because the goal is behavioral parity first and performance second. The wheels remove the need for a Rust toolchain, which is what makes a drop-in swap practical for a Python team that only wants faster graph calls today.

How behavior is enforced

The contract is enforced by tooling rather than by intention. A 377-file Python parity test suite compares FrankenNetworkX against NetworkX call by call across thousands of fixtures, including iteration order, exception class, and error wording. A curated Rust differential conformance harness and five auto-generated audit ledgers fail CI if a measured public symbol drifts. The ledgers cover a coverage matrix, raw versus public symbols, delegation, upstream divergence, and API ergonomics. The current structural surface is not 100 percent. Against the pinned NetworkX 3.6.1 FeatureUniverse, FrankenNetworkX reports 3,399 strictly present paths out of 4,129 applicable paths, which is 82.3 percent, with 700 partial and 30 missing. The TieBreakPolicy, named CGSE, pins tie-breaks at the type level with 13 variants, and a ComplexityWitness records a length-prefixed Blake3 decision-path ledger for each call. RaptorQ erasure-coded sidecars store durable conformance artifacts with decode-proof receipts. The design rejects subclassing, data copying wrappers, and clean-slate Rust APIs because each of those loses behavioral parity or forces a rewrite, and it favors porting algorithms into native Rust while preserving observable behavior on implemented paths, which is a disciplined engineering choice. The 82.3 percent figure is reported honestly rather than rounded up, so a reader knows which calls still fall back to pure Python during a transition period.

Using it as a backend

FrankenNetworkX offers two ways to use it. As a standalone library you replace `import networkx` with `import franken_networkx as fnx` and call the same functions, such as shortest_path, pagerank, connected_components, betweenness_centrality, and minimum_spanning_tree, which return the exact same results as NetworkX would. As a NetworkX backend you set `nx.config.backend_priority` to include franken_networkx once, and supported algorithms dispatch into Rust transparently, with many unsupported algorithms falling back to NetworkX. The backend is registered through Python entry points in pyproject.toml, so NetworkX picks it up automatically after install. The library implements four core graph types that match NetworkX: Graph, DiGraph, MultiGraph, and MultiDiGraph, with the same method surface for adding nodes and edges, subgraphs, copy, direction conversions, and adjacency access. MultiGraph variants collapse parallel edges transparently when a simple-graph algorithm runs. The algorithm catalog spans more than 25 families, including shortest path, connectivity, centrality, clustering, matching, flow, trees, Euler paths, traversal, DAG, link prediction, community, isomorphism, planarity, approximation, generators, I/O, NumPy and SciPy and pandas interop, conversion, and drawing layouts that delegate to NetworkX and matplotlib, which covers most everyday graph work. The four matching graph types mean existing code that builds a DiGraph keeps working, since the constructors share the same names and the same method surface as before.

Coverage and honesty

The README is candid about what FrankenNetworkX is and is not. If the only need is the fastest possible PageRank on a huge graph and API shape or tie-break semantics do not matter, igraph, graph-tool, or a GPU library may beat it on raw throughput for that single call. If the need is an existing NetworkX codebase that should keep working without rewriting and without subtle behavior changes, FrankenNetworkX is built for that case. The comparison table places it against igraph, graph-tool, rustworkx, graspologic, networkx-cuda, and cugraph, noting where each diverges on API style, drop-in fit, tie-break parity, and coverage. The 316 algorithms registered in backend.py form the dispatch surface, and the generated FeatureUniverse records every gap and exclusion rather than rounding up to full parity. The architecture layers a Python package over a PyO3 cdylib that releases the GIL at hot paths, with crates for classes, algorithms, generators, read and write, CGSE, views, runtime, dispatch, convert, conformance, and durability. The license is MIT per the README badges, while the repository metadata lists NOASSERTION, a discrepancy worth noting for redistributors who need a clear license file. The MIT badge and the NOASSERTION metadata disagree, so a user should check the LICENSE file before relying on the stated terms for a commercial or redistributed use.

Editorial conclusion

FrankenNetworkX is written in Python with a Rust core, reports 82.3 percent strict import and signature coverage against NetworkX 3.6.1, and its repository was last updated on 2026-08-24.