NetworkX 3.x Backend Dispatch: Pin Priority or Accept Environment-Dependent Fallback?

Direct Answer

Treat automatic backend-to-core conversion as a compatibility feature to disable, not a safety net. Configure fail-fast behavior so missing backends raise immediately. Pin priority at the project level (e.g., pyproject.toml or a shared config file) and reinforce it with explicit per-call arguments in critical paths. Do not rely on NETWORKX_BACKEND_PRIORITY alone — it is too easily overridden by shell differences between developer machines and CI runners.

Why This Matters

NetworkX 3.x discovers backends at import time via entry points. If your lockfile pins networkx but leaves optional providers (e.g., networkx-cugraph, graphblas-algorithms) unpinned, a pip install in CI can pull a different backend version — or none at all — without any code change. When a backend cannot handle a graph, NetworkX may silently convert to the pure-Python reference implementation. On large graphs that fallback can dominate runtime, making local vs. CI timings incomparable and hiding missing dependencies.

Confirmed Facts

• Backend selection order: per-call backend= argument > NETWORKX_BACKEND_PRIORITY env var > entry-point registration order (varies by minor release).
• Fallback to the default (pure-Python) backend is silent unless you inspect networkx.backend.get_current_backend() or catch the internal BackendNotImplementedError.
• Pinning only networkx==3.x.y in a lockfile does not pin backend providers; they must be listed explicitly.

Likely Explanation (Not Yet Verified in All 3.x Minors)

The exact env-var name and default priority list have shifted between 3.0, 3.1, and 3.2. The 3.2 release notes are the authoritative source for your pinned version. Assume the precedence above holds, but verify with a one-liner in your actual environments.

Steps to Enforce Reproducible Dispatch

1. Pin every backend provider in your lockfile (requirements.txt, poetry.lock, uv.lock, etc.) alongside networkx.
2. Add a project-level config (e.g., [tool.networkx] backend_priority = ["cugraph", "graphblas", "networkx"] in pyproject.toml) and read it at startup to set os.environ["NETWORKX_BACKEND_PRIORITY"] before importing NetworkX.
3. Opt into fail-fast by setting NETWORKX_BACKEND_FAIL_MISSING=1 (available 3.1+) or wrapping calls with a small helper that raises if get_current_backend() returns "networkx" when a GPU backend was expected.
4. Use explicit backend= arguments in performance-critical call sites (e.g., nx.pagerank(G, backend="cugraph")) so the intent is visible in code review and cannot be overridden by env drift.
5. Verify in CI: add a test that asserts networkx.backend.get_current_backend() == "cugraph" (or your chosen backend) for a representative graph.

One Diagnostic Check

Run this in both your local shell and the CI job before the test suite:

python -c "import networkx as nx; print(nx.backend.get_current_backend())"

If the output differs, your priority configuration is not resolving identically — fix the config or the lockfile before proceeding.