Registry / http-networking / pyroute2

pyroute2

JSON →
library0.9.6pypypi✓ verified 28d ago

pyroute2 is a pure Python library for Linux network management using the Netlink socket API. It provides a programmatic interface to the same functionality as `iproute2` utilities, supporting various Netlink protocols like RTNL (IP settings, routing), WireGuard, nftables, nl80211 (WiFi), and more. Starting from version 0.9.1, its core has been rewritten to be `asyncio`-based, with synchronous APIs implemented as wrappers for compatibility. The current version is 0.9.5, with an active release cadence.

pip install pyroute2
INSTALL
IMPORT
SIG · PYROUTE2
P
pyroute2
http-networkingpythonv0.9.6
Install
1.9s avg
Import
675ms
Disk
21MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v0.9.6 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.718s · 22.2MB
glibc
py 3.10–3.95 runs
installs and imports cleanly · install 1.9s · import 0.632s · 23MB
21MB installed
● package 21MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

IPRoute
✓ from pyroute2 import IPRoute
Synchronous RTNL (routing) API, implemented as a wrapper around the asyncio core.
AsyncIPRoute
✓ from pyroute2 import AsyncIPRoute
Asynchronous RTNL (routing) API, the primary interface since v0.9.1.
NDB
✓ from pyroute2 import NDB
High-level, transactional API for network settings, designed to replace IPDB.
NetNS
✓ from pyroute2 import NetNS
Legacy class for network namespace management; in newer versions, use `netns` argument directly with `IPRoute` or `AsyncIPRoute`.
IPDB
✓ from pyroute2 import IPDB
✗ from pyroute2 import IPDB
IPDB is officially deprecated since v0.7.12 and removed from the library in recent versions, serving only as a minimal compatibility wrapper around NDB. It should not be used for new projects.

This quickstart demonstrates how to use the synchronous `IPRoute` API to list network interfaces on a Linux system. It's crucial to note that `pyroute2` operations typically require root privileges or `CAP_NET_ADMIN` capabilities. The example includes comments on how to adapt for asynchronous usage with `AsyncIPRoute`.

import os from pyroute2 import IPRoute # Note: pyroute2 operations often require root privileges. # It's highly recommended to run this script with 'sudo python your_script.py' # or ensure the user has CAP_NET_ADMIN capability. # For a non-root setup (e.g., remote access), consider RemoteIPRoute with mitogen. # Synchronous example: List network interfaces try: with IPRoute() as ipr: # Get all link (interface) objects links = ipr.get_links() print("\nNetwork Interfaces:") for link in links: # Access attributes using .get_attr() or dictionary-like access ifname = link.get_attr('IFLA_IFNAME') state = link.get_attr('IFLA_OPERSTATE') or 'UNKNOWN' address = link.get_attr('IFLA_ADDRESS') or 'N/A' index = link['index'] print(f" Index: {index}, Name: {ifname}, State: {state}, MAC: {address}") # Asynchronous example (requires `await` in an async function): # import asyncio # from pyroute2 import AsyncIPRoute # async def async_main(): # async with AsyncIPRoute() as ipr: # print("\nAsync Network Interfaces:") # async for link in await ipr.link("dump"): # ifname = link.get("ifname") # state = link.get("state") # address = link.get("address") # print(f" Name: {ifname}, State: {state}, MAC: {address}") # asyncio.run(async_main()) except PermissionError: print("\nPermission denied. Most pyroute2 operations require root privileges (e.g., run with 'sudo').") except Exception as e: print(f"\nAn error occurred: {e}")
Debug
Known issues
breakingThe core of pyroute2 was entirely rewritten to be `asyncio`-based in version 0.9.1. While a synchronous API (`IPRoute`) is provided for compatibility, it's now a wrapper around the asynchronous core. Direct low-level socket operations (`recv()`, `sendmsg()`) are no longer directly supported on socket objects controlled by the asyncio event loop.
fix
For new development, prioritize using `AsyncIPRoute` and `await`able methods within `async` functions. For existing synchronous code, ensure you use the `IPRoute` context manager (`with IPRoute() as ipr:`) and adapt to its API, noting that some low-level socket interactions might need refactoring.
affects: >=0.9.1
deprecatedThe `IPDB` module, a high-level transactional database for network settings, has been deprecated since v0.7.12 and largely removed, serving only as a compatibility wrapper for `NDB`. It is explicitly advised *not* to use `IPDB` for new projects.
fix
Migrate from `IPDB` to the `NDB` (Netlink Database) module, which offers a robust, high-level API with a different architecture.
affects: >=0.7.12 (deprecated), >=0.9.0 (effectively removed/wrapper)
deprecatedThe `NDB` (Netlink Database) CLI (Command Line Interface) was deprecated and removed in version 0.9.3rc1. The `NDB` Python API itself remains active and is the recommended high-level interface.
fix
If you were using the `NDB` CLI, you will need to replace its functionality with equivalent Python API calls using the `pyroute2.NDB` module.
affects: >=0.9.3rc1
gotchaMost operations performed by `pyroute2` (e.g., modifying network interfaces, routes, addresses) require root privileges (`sudo`) or the `CAP_NET_ADMIN` capability. Running scripts without these permissions will result in `PermissionError` or similar failures.
fix
Execute your Python script with `sudo` (e.g., `sudo python your_script.py`) or ensure the user executing the script has the necessary Linux capabilities.
affects: All versions
gotchaFor synchronous `IPRoute` or other socket-based objects, it's crucial to explicitly release resources and close sockets to prevent resource leaks. While Python's garbage collection will eventually close file descriptors, explicit closure is best practice.
fix
Always use `IPRoute` (and similar classes) as a context manager (`with IPRoute() as ipr:`) to ensure sockets are properly closed, even if errors occur.
affects: All versions
gotchaWhen managing network namespaces in multithreaded applications, `pyroute2.config.child_process_mode` defaults to 'fork', which is not thread-safe and can lead to warnings.
fix
In multithreaded applications that create network namespaces, set `pyroute2.config.child_process_mode = 'mp'` (for `multiprocessing.Process()`) for a safer, albeit potentially slower, operation. `from pyroute2.config import setup; setup.child_process_mode = 'mp'`
affects: All versions
Upgrade
Version history
0.9.6latest on PyPI · released Apr 15, 2026
Audit
Dependencies

No dependency data recorded yet.

Agent activity
16 hits · last 30 days
node
14
Resources
pyroute2 — pip install pyroute2 · libregistry