Skip to main content

p4net

CI PyPI Python Versions License Documentation Status

A P4Runtime-native SDN simulation framework for BMv2.

Status: 1.9.0, stable. Public APIs follow the API stability rules. See the changelog for new features, fixes and upgrade notes.

Features

  • P4Runtime-native control plane.
  • BMv2 simple_switch_grpc data plane.
  • Linux network-namespace based hosts.
  • veth-based links with tc/netem impairment.
  • Programmable Python topology DSL.
  • Interactive CLI.
  • Per-port packet capture.
  • P4Runtime CPU-port packet I/O (<switch> packet send / listen).
  • IPv4 and IPv6 host addressing with per-interface sysctl gating.
  • Asymmetric link impairment (per-direction bandwidth, delay, jitter, loss_pct).
  • Topology visualization (Graphviz DOT / PNG / SVG).
  • In-band network telemetry (INT) — single-switch introduction plus a multi-hop production-style example with wall-clock-aligned cross-switch timestamps via RunningSwitch.boot_timestamp_us.
  • Direct P4 register read/write via P4Runtime gRPC.
  • Unified p4net.* logger hierarchy with CLI verbosity control.
  • Async P4Runtime client (AsyncP4RuntimeClient, Stable since 1.7.0) for concurrent multi-switch operations.
  • No OpenFlow, no Open vSwitch, no Docker.

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

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.9.0
File Size Uploaded Provenance Actions
p4net-1.9.0.tar.gz 536.2 kB With provenance Details for p4net-1.9.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for p4net 1.9.0
File Interpreter ABI Platform Actions
p4net-1.9.0-py3-none-any.whl Python 3 none any Details for p4net-1.9.0-py3-none-any.whl

Total release size: 642.2 kB

Release files / p4net-1.9.0.tar.gz

Download URL p4net-1.9.0.tar.gz
Size 536.2 kB
Tags Source
SHA-256 checksum
How to use checksums
a77ef95e8e17d3eb209ab554e931f1137771af9488e899d85441de7fdfa2cab1
BLAKE2b-256 checksum
How to use checksums
7445d046b3ae32107b19b308dc9cbb0ea70a79a084c4985653eec3b7c988f290
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 19, 2026.

Transparency log

Release files / p4net-1.9.0-py3-none-any.whl

Download URL p4net-1.9.0-py3-none-any.whl
Size 105.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
133b2d7ef64af73018b527bc343fa05cae9d06cbe6062a732e628c4fd9719f7c
BLAKE2b-256 checksum
How to use checksums
bc2c61ac80450fc843328ac2770b7bf15f091438df196489028dfd4fe12810b1
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 19, 2026.

Transparency log

Security for p4net 1.9.0

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.9.0.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 19, 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