Skip to main content

P4Net

CI PyPI Python Versions License Documentation Status

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 AsyncP4RuntimeClient to 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_ADMIN to 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-direction delay shaping.
  • 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)

Source distribution for p4net 1.10.1
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)

Table of built distributions (wheels) for p4net 1.10.1
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page