# HyperNetX gives Python one data structure for every hypergraph > HyperNetX is a Pacific Northwest National Laboratory library for building and analysing hypergraphs, generalised to work over Pandas dataframes with one underlying structure for every hypergraph. The 2.x rewrite removed the static and dynamic distinction and broke backwards compatibility, which is the first thing to check before porting older code. **pnnl/HyperNetX** — Python package for hypergraph analysis and visualization. - Repository: https://github.com/pnnl/HyperNetX - Website: https://hypernetx.readthedocs.io - Stars: 721 · Forks: 118 - Language: Python - License: NOASSERTION - Published: 2026-10-21 · Updated: 2026-10-21 · Language: en - Canonical page: https://hysenlabs.com/projects/pnnl-hypernetx ## A laboratory library for data that is naturally a hypergraph The HyperNetX library provides classes and methods for the analysis and visualization of complex network data modeled as hypergraphs, and the README states plainly that the library generalizes traditional graph metrics. That generalization is the whole point. A graph edge connects two nodes. A hypergraph edge can connect any number of nodes, which is the shape you get the moment your entities are related to each other rather than owned by one another. A paper with five co-authors, a set of genes implicated in a pathway, a group of people who attended the same sessions: these are hyperedges, and most graph tooling makes you either flatten them into a bipartite graph or throw the structure away. The provenance explains the design. HNX was originally developed by the Pacific Northwest National Laboratory for the Hypernets project as part of its High Performance Data Analytics program, and it is currently maintained by scientists at PNNL, with community contributions and bug fixes welcomed. PNNL is operated by Battelle Memorial Institute under Contract DE-ACO5-76RL01830. The project names its people, which is unusual and useful. Brenda Praggastis is principal developer and designer, the development team is Praggastis, Audun Myers, Greg Roek and Ryan Danehy, visualization is Dustin Arendt and Ji Young Yun, Cliff Joslyn is principal investigator, and Brian Kritzstein is program manager, with a longer list of principal contributors behind design, theory and code. The stated audience is researchers modelling data as hypergraphs, and the library ships as a normal PyPI package with readthedocs documentation. ## Version 2.3 removed the static and dynamic distinction The release notes for version 2.3 describe a refactor rather than a feature addition. The core library was refactored to take better advantage of Pandas dataframes, improve readability and maintainability, address bugs, and make it easier to change. The structural change is the interesting one. The static and dynamic distinctions no longer exist. All hypergraphs use the same underlying data structure, supported by Pandas dataFrames, and all hypergraphs maintain a state_dict to avoid repeating computations. That state_dict is worth understanding. Many hypergraph operations are expensive to recompute, for example the connectivity or centrality of a large structure. Keeping the derived state alongside the structure means a second call does not pay the cost again, at the price of having to invalidate that state when the hypergraph is modified. The rest of the changes in 2.3 are equally concrete. Hypergraph now supports adding and removing edges, nodes and incidences, and it supports the sum, difference, union and intersection of a hypergraph with another hypergraph. There are new factory methods supporting the Hypergraph constructor, and the constructors accept cell, edge and node metadata. Two class-level changes matter for anyone with existing code. EntitySet has been replaced by HypergraphView, and IncidenceStore and PropertyStore are new classes that maintain the structure and the attributes of a hypergraph. The nwhy optimizations are no longer supported. Being able to compute the union of two hypergraphs is a bigger deal than it sounds. Set algebra on structures is what makes hypergraph analysis composable, and the fact that it arrives in the same release as mutable structures suggests the data model was being reshaped around that. ## Upgrading from 2.2 means rebuilding your objects The release notes carry an explicit warning that is easy to skim past. Version 2.3 is not backwards compatible, and objects constructed using earlier versions can be imported using their incidence dictionaries and/or property dataframes. That sentence defines the migration path precisely. It is not that old objects break silently, and it is not that the library is abandoned. There is an import route, and it runs through the two data structures the new design is built on, the incidence dictionary and the property dataframes, which is a sensible way to migrate since those are exactly the pieces the refactor made canonical. The Python requirement moved at the same time, to >=3.10,<4.0.0. The README lists the current requirement in the prerequisites section as Python >=3.10,<4.0.0, and the pyproject file pins the same range. This is the single most important practical fact about the library for an existing user, and it argues for checking the version before writing any code against it. A project pinned to an older HNX release will not pick up the arithmetic, the mutability or the unified data structure, and a project that upgrades blindly will find that its saved objects no longer load. The CHANGELOG.md file at the root of the repository is the reference for what changed between versions, and the tutorials directory holds notebooks that show the current API. ## Installing into a virtual environment The recommended installation method for most users is to create a virtual environment and install HyperNetX from PyPi, and the package is also available by cloning or forking the GitHub repository. The venv route is two commands. ```shell python -m venv venv-hnx source venv-hnx/bin/activate ``` The conda route is the equivalent for users who already work with conda. ```shell conda create -n venv-hnx python=3.11 -y conda activate venv-hnx ``` Note that the conda example pins Python 3.11, which sits inside the supported >=3.10,<4.0.0 range. The README also documents a virtualenv option, and the environment name is the same in both cases. The package name on PyPI is hypernetx, and the pyproject file records the version as 2.4.3 with the description that HyperNetX is a Python library for the creation and study of hypergraphs. The pyproject file also carries the package layout, with the hypernetx package split into algorithms, classes, drawing, reports and utils, plus a utils/toys subpackage for the example networks. The build system is Poetry, and the repository has a pyproject.toml, a requirements.txt, a tox.ini, a Makefile, a .pre-commit-config.yaml, a .flake8 and a pylintrc, so the project is set up for a fairly standard Python contribution workflow. ## The dependency list is a map of the feature surface Reading the declared dependencies tells you what the library actually does, and the list is more informative than the feature descriptions. The core is networkx at >=3.3 and pandas at <3.0.0, which is the graph library the metrics generalise and the dataframe layer the data model is built on. scikit-learn at >=1.4.2 and scipy at >=1.13 bring the numerical machinery, and igraph at >=0.11.4 provides a second graph engine for the algorithms that benefit from it. The visualisation side is matplotlib at >=3.10.6 and plotly at >=6.3.0, with the concepts and bitsets packages, which support hypergraph-specific operations, and fastjsonschema at >=2.21.2, which is what validates data against the JSON schemas of the interchange format. requests at ^2.32.3 is there, and oat-python at >=0.1.1 and celluloid at >=0.2.0 cover the homology and temporal extras respectively. The extras are declared explicitly. The embeddings extra pulls in torch and torchvision, the temporal extra pulls in celluloid, and the homology extra pulls in plotly and oat-python. That last point is a practical trap. Homology and embeddings are opt-in, so a plain install does not give you them, and a notebook that imports an optional namespace will fail with an import error rather than a helpful message about an extra. There is also an optional widget group with jupyter-dash, dash, ipywidgets, notebook and jupyter-contrib-nbextensions, and a tutorials group, both marked optional. The widget group is what backs the interactive elements in the notebooks. ## Notebooks first, containers second The repository leads with tutorials rather than with an API reference, and the six Colab badges at the top of the README are the fastest way to see what the library does. The set covers HNX Basics, Visualization Methods, a LesMis case study, a LesMis visualisation book tour, an attributed hypergraph, and hypergraph arithmetic. Each one opens in Google Colab from the tutorials/basic directory in the repository, and further notebooks can be run as Jupyter notebooks from the tutorials directory. The Docker side is for the notebooks rather than for the library as a service. The compose file defines a single service from the hypernetx/hypernetx:latest image, mapping port 8888 to 8888 with a tty and stdin open, and mounting the working directory into the container. ```yaml image: hypernetx/hypernetx:latest ports: - "8888:8888" tty: true stdin_open: true volumes: - "${PWD}:/home/jovyan/work" ``` The Dockerfile is a multistage build that copies only the tutorial notebooks into the image, and the comment says so. The final image installs the latest versions of HyperNetX and HNXWidget from PyPi. ```dockerfile RUN pip install --no-cache-dir hypernetx hnxwidget ``` One setting is worth flagging for anyone exposing this locally. ```dockerfile ENTRYPOINT ["start-notebook.py", "--IdentityProvider.token=''"] ``` The notebook server is started with the identity provider token set to an empty string, so the Jupyter server requires no token to access the URL. On a shared machine that means anyone who can reach port 8888 can run code in the container, and the volume mount gives them the working directory as well. ## HIF gives the hypergraph libraries a common format Hypergraph analysis is fragmented, and the README addresses that directly. HNX is a primary contributor to the Hypergraph Interchange Format, a JSON schema for sharing data modeled as hypergraphs, and the specification and sample notebooks are hosted in a separate HIF-standard repository. The point of a format like this is that a hypergraph you built in one tool can be handed to another. The README lists the other libraries using the standard: HypergraphX (HGX) in Python, CompleX Group Interactions (XGI) in Python, SimpleHypergraphs.jl in Julia, and the Hypergraph-Analysis-Toolbox in Python. That is a healthier position than it looks. Hypergraph tooling is young, and the risk for a user is investing in one library's object model and then finding it cannot be exported. A shared JSON schema with sample notebooks reduces that risk, and the presence of the fastjsonschema dependency in the package suggests validation against the schema is part of the import path rather than an afterthought. For questions and comments, the README directs users to the developers directly at the PNNL contact address, hypernetx@pnnl.gov. ## Licence, versions and who is doing the work The licence needs a note, because the two sources describe it differently. The project listing records a custom licence that the hosting platform could not classify, with the terms in the LICENSE.rst file, while the pyproject file declares license as 3-Clause BSD license. The LICENSE.rst file is the document that governs use. A 3-Clause BSD licence is a permissive choice with no copyleft obligation, which is the normal expectation for a US national laboratory research library, and it is compatible with most commercial and academic use. The DISCLAIMER.txt file at the root of the repository is a separate item to be aware of, and the CITATION.cff file, with its own CI workflow, is how the project wants itself cited. On maintenance, the last push was on 2026-07-08 and the repository is not archived, so work is happening. The recent releases are v2.4.3 and v2.4.2, both on 2026-04-14, and v2.4.1 on 2025-04-17, which is a gap of a year between the last two minor lines and a sign that the project ships in bursts rather than continuously. The repository also carries a HNX_Paper/ directory, a CHANGELOG.md, a CODE_OF_CONDUCT.md and a CONTRIBUTING.md, and the README points to the contributor guide in the documentation for how to get involved. For a library that started inside a laboratory programme and is now maintained by working scientists with community contributions encouraged, that combination of a paper directory and a contributor guide is the shape you would expect. ## Conclusion Use HyperNetX if your data is naturally a hypergraph and you want graph metrics, arithmetic on hypergraphs and notebooks that run in Colab without a local environment. Do not adopt it for ordinary graphs, and do not reuse 2.2 or earlier code unchanged, because version 2.3 is explicitly not backwards compatible and objects from earlier versions have to be re-imported through incidence dictionaries or property dataframes. Before starting, check the Python requirement of 3.10 or newer and confirm that the optional extras you need, such as homology or embeddings, are installed rather than assumed. ## FAQ ### What is HyperNetX used for? It provides classes and methods for the analysis and visualization of complex network data modeled as hypergraphs, and it generalizes traditional graph metrics. The library is intended for researchers modelling data as hypergraphs. ### Is HyperNetX 2.3 backwards compatible with earlier versions? No. The release notes state that version 2.3 is not backwards compatible, and that objects constructed using earlier versions can be imported using their incidence dictionaries and/or property dataframes. ### Which Python versions does HyperNetX support? HyperNetX officially supports Python >=3.10,<4.0.0, and the pyproject file pins the same range with a dependency on pandas <3.0.0. ### How do I install HyperNetX? The recommended method is to create a virtual environment and install it from PyPI. The README shows python -m venv venv-hnx followed by source venv-hnx/bin/activate, and an equivalent conda create -n venv-hnx python=3.11 -y for conda users. It can also be cloned or forked from GitHub. ### What changed in HyperNetX 2.3? The static and dynamic distinctions were removed, so all hypergraphs use the same Pandas backed data structure and keep a state_dict, and the nwhy optimizations are no longer supported. Hypergraphs gained the ability to add and remove edges, nodes and incidences, plus sum, difference, union and intersection operations, EntitySet was replaced by HypergraphView, and IncidenceStore and PropertyStore are new classes. ### What is the Hypergraph Interchange Format? HIF is a JSON schema for sharing data modeled as hypergraphs, and HNX is a primary contributor to it, with the specification and sample notebooks in the HIF-standard repository. Other libraries using the standard include HypergraphX, XGI, SimpleHypergraphs.jl and the Hypergraph-Analysis-Toolbox. ## Sources - [Issues](https://github.com/pnnl/HyperNetX/issues) - [pnnl/HyperNetX on GitHub](https://github.com/pnnl/HyperNetX) - [Project website](https://hypernetx.readthedocs.io) - [README](https://github.com/pnnl/HyperNetX/blob/master/README.md) - [Releases](https://github.com/pnnl/HyperNetX/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/pnnl-hypernetx