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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.718s · 22.2MB
glibcpy 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.fixFor 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.fixMigrate 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.fixIf 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.fixExecute 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.fixAlways 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.fixIn 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.