nmcli: Python wrapper for NetworkManager CLI

1.7.0 verified Sat May 09 auth: no python

A Python wrapper library for the network-manager CLI client (nmcli). Current version 1.7.0, requires Python >=3.7. Maintained, with frequent releases adding new features.

pip install nmcli

Common errors

error ModuleNotFoundError: No module named 'nmcli' ↓

cause Library not installed or installed in a different environment.

fix

Run: pip install nmcli

error nmcli.connection.show() AttributeError: 'Connection' object has no attribute 'show' ↓

cause Incorrect import or old version. show() was added in v1.0.0, but as a module function, not a method on Connection objects.

fix

Use: nmcli.connection.show() directly, not on a connection instance.

error RuntimeError: There is no current event loop in thread 'MainThread'. ↓

cause Trying to use asyncio.run() or similar without proper async wrapper around synchronous library.

fix

Wrap synchronous calls: await loop.run_in_executor(None, nmcli.connection.show) or use a sync context.

Warnings

breaking In v1.4.0, nmcli.general was fixed to work with nmcli client >= 1.48.x. Code relying on older parsing may break if the nmcli output format changed. ↓

fix Upgrade to >=1.4.0 and test general methods like nmcli.general.status()

gotcha This library is NOT async. Many users try to use it with asyncio and get RuntimeError due to blocking subprocess calls. ↓

fix Run synchronous calls in a thread pool executor if using asyncio

gotcha Methods like wifi_connect() require root privileges or appropriate polkit permissions. Common failure due to missing D-Bus authorization. ↓

fix Run the script as root or configure polkit to allow unprivileged users to manage networking

Imports

nmcli
wrong
```
from nmcli import nmcli
```
correct
```
import nmcli
```
The top-level is a module, not a submodule.

Quickstart

Quick start: import nmcli and use methods like connection.show_all() and device.wifi()

import nmcli

# Show all network connections
connections = nmcli.connection.show_all()
for conn in connections:
    print(conn.name, conn.type)

# Get device wifi list
import os
os.environ.get('WIFI_PASSWORD', '')  # dummy auth
wifi_list = nmcli.device.wifi()
for ap in wifi_list:
    print(ap.ssid, ap.signal)