P4Net
P4Net is a Python framework for BMv2 and P4Runtime experiments on Linux.
Status: 1.10.1, stable. Public APIs follow the API stability rules. See the changelog for new features, fixes and upgrade notes.
Why use P4Net
- Start BMv2 with P4Runtime in one command. P4Net compiles the P4 programs, builds the Linux topology, starts BMv2, connects the built-in P4Runtime client, and installs the pipelines.
- Reuse one topology for debugging and automated tests. Define hosts, links, and switches in Python. Put initial table entries in
setup(net)and reuse that function with the same topology in a Python test. - Debug hosts and switches in one shell. Check connectivity, run host commands, and use P4Runtime to inspect or program tables, read counters, and handle PacketIn and PacketOut. See the L3 forwarding example.
- Configure several switches concurrently. Use
AsyncP4RuntimeClientto send P4Runtime requests from one Python event loop. The async example installs forwarding entries on a three-switch mesh. - Repeat experiments under defined link conditions. Configure IPv4 and IPv6 hosts, set bandwidth, delay, jitter, and loss per direction, and capture traffic on switch ports.
Requirements
- Linux kernel >= 5.4.
- Python 3.10+.
- BMv2 and p4c installed system-wide.
- Root or
CAP_NET_ADMINto manage namespaces and veth devices.
Installation
Follow the installation guide to set up p4c, BMv2 and the p4net CLI. For an editable checkout and development tools, see Contributing.
Quick Start
from pathlib import Path
from p4net import Network
from p4net.topo import Topology
topo = Topology()
h1 = topo.add_host("h1", ip="10.0.0.1/24", mac="00:00:00:00:00:01")
h2 = topo.add_host("h2", ip="10.0.0.2/24", mac="00:00:00:00:00:02")
s1 = topo.add_switch("s1", p4_src=Path("quick_start.p4"))
topo.add_link(h1, s1, port_b=1)
topo.add_link(h2, s1, port_b=2)
with Network(topo) as net:
print(net.pingall())
A complete runnable version, including the matching quick_start.p4 (a port-2-port swap that needs no runtime table programming) and a tiny static-ARP setup, lives in examples/quick_start/. After installing the CLI, clone the repository and run the example to open the interactive shell.
git clone https://github.com/zhh2001/p4net.git
cd p4net
sudo p4net examples/quick_start/quick_start.py
The console script loads a Python file that defines a module-level topology: Topology and optionally setup(net). The example README also shows how to run the file directly with Python.
Examples
examples/quick_start/— minimal two-host network with a hardcoded port-swap pipeline.examples/l3_forwarding/— runtime-programmed IPv4 LPM with static ARP.examples/cpu_punt/— every dataplane packet punted to the controller; demonstrates<switch> packet send/<switch> packet listen.examples/dual_stack/— two hosts carrying both IPv4 and IPv6.examples/asymmetric_link/— per-directiondelayshaping.examples/ipv6_lpm/— runtime-programmed IPv6 LPM forwarding.examples/int/— single-switch in-band network telemetry: the pipeline inserts a 14-byte INT shim into every forwarded packet; a raw-socket listener decodes it on the receiver.examples/int_multi_hop/— multi-hop INT on a two-switch linear path; the listener decodes the full hop-by-hop stack. Production-style telemetry topology.
Documentation
Full documentation: https://zhh2001.github.io/p4net/
The English site is the authoritative reference; a Chinese translation layer is being added incrementally. Pages on the site cover installation, a tutorial, an architecture overview, the CLI reference, the auto-generated API reference, troubleshooting, a glossary, and per-example walk-throughs.
The source for these pages lives under docs/ and is built with MkDocs Material.
License
Apache-2.0.
Metadata
Release files for p4net 1.10.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| p4net-1.10.1.tar.gz | 536.1 kB | With provenance | Details for p4net-1.10.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| p4net-1.10.1-py3-none-any.whl | Python 3 | none | any | Details for p4net-1.10.1-py3-none-any.whl |
Total release size: 646.3 kB
Release files / p4net-1.10.1.tar.gz
| Download URL | p4net-1.10.1.tar.gz |
|---|---|
| Size | 536.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c2d3d7ee5ffdfe107eca60f9cba4b11b7cd8aa242cb35b935d75f97e595464ce
|
|
BLAKE2b-256 checksum How to use checksums |
0d3297db94c0093cf36b17c86bcfa6dceb7018ea4dcbdef440ffa9bf86cc3c43
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.
Transparency logRelease files / p4net-1.10.1-py3-none-any.whl
| Download URL | p4net-1.10.1-py3-none-any.whl |
|---|---|
| Size | 110.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a56cdd1df72de5b515d6d9ed6a4c827a1886ea47a53a9efa86c40820dd0991b1
|
|
BLAKE2b-256 checksum How to use checksums |
c6f42c29b52d49db6e8df47ec5012b298839255c15e2db560af148b844578592
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.
Transparency logSecurity for p4net 1.10.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for p4net-1.10.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.