Skip to main content

p4net

CI PyPI Python Versions License Documentation Status

A P4Runtime-native SDN simulation framework for BMv2.

Status: 1.10.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.10.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.10.0
File Size Uploaded Provenance Actions
p4net-1.10.0.tar.gz 545.1 kB With provenance Details for p4net-1.10.0.tar.gz

Built distribution (wheel)

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

Total release size: 655.6 kB

Release files / p4net-1.10.0.tar.gz

Download URL p4net-1.10.0.tar.gz
Size 545.1 kB
Tags Source
SHA-256 checksum
How to use checksums
6c4995b5854f924aecdda1b979ffb9f8e297f0643846e872028b8e16d34dc1a0
BLAKE2b-256 checksum
How to use checksums
7091e420526b9738d6dbf135c62e679077199d3df221f0fdd99cccf8e19fd648
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 20, 2026.

Transparency log

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

Download URL p4net-1.10.0-py3-none-any.whl
Size 110.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b8ccebb1285c7f48b30f0cdff9f37da5c3fc2635b76e5b9210615914fe72b409
BLAKE2b-256 checksum
How to use checksums
12ac5b7e8b5207d70446a35da8ae5e2b0b0b73f6b0f2fb3775d2174e20e286bf
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 20, 2026.

Transparency log

Security for p4net 1.10.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.10.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 20, 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