Skip to main content

p4net

CI PyPI Python Versions License Documentation Status

A P4Runtime-native SDN simulation framework for BMv2.

Status: 1.8.2, 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.8.2

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.8.2
File Size Uploaded Provenance Actions
p4net-1.8.2.tar.gz 530.5 kB With provenance Details for p4net-1.8.2.tar.gz

Built distribution (wheel)

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

Total release size: 635.4 kB

Release files / p4net-1.8.2.tar.gz

Download URL p4net-1.8.2.tar.gz
Size 530.5 kB
Tags Source
SHA-256 checksum
How to use checksums
724fd0066ddf4c8dc9d83a1f69c9c8696dcc47e04ce7c779e565a0fe75a1e132
BLAKE2b-256 checksum
How to use checksums
90c708f891d20f1cbb11b39a396dd16a14a1702bea7e86fa9d0cbca3b75ccf73
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.8.2-py3-none-any.whl

Download URL p4net-1.8.2-py3-none-any.whl
Size 104.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6e2aee241ee7cb241cc3cf8db3df5f34f1d2168b58cb71d59c81dfaa401a18f2
BLAKE2b-256 checksum
How to use checksums
10bdd7c8eddc7112ad0840dba0e852abb3e559667a2e37caae99791067d18eba
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.8.2

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