pyroute2: Python Netlink library

0.9.5 · active · verified Fri Apr 10

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.

Warnings

breaking The 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.
deprecated The `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.
deprecated The `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.
gotcha Most 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.
gotcha For 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.
gotcha When 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'`

Install

pip install pyroute2 Install stable version

Imports

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

Quickstart

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}")

view raw JSON →