Skip to main content

Declarative network manager API

Project description

We are Nmstate!

A declarative network manager API for hosts.

CI Coverage Status PyPI version Fedora Rawhide version Code Style Language grade: Python

Copr build status, all repos are built for Fedora 31+ and RHEL/CentOS/EPEL 8:

  • Latest release: Latest release Copr build status
  • Git base: Git base Copr build status
  • Latest 0.2 release: Latest 0.2 release Copr build status
  • Git nmstate-0.2: Git nmstate-0.2 Copr build status
  • Latest 0.3 release: Latest 0.3 release Copr build status
  • Git nmstate-0.3: Git nmstate-0.3 Copr build status

What is it?

Nmstate is a library with an accompanying command line tool that manages host networking settings in a declarative manner. The networking state is described by a pre-defined schema. Reporting of current state and changes to it (desired state) both conform to the schema.

Nmstate is aimed to satisfy enterprise needs to manage host networking through a northbound declarative API and multi provider support on the southbound. NetworkManager acts as the main (and currently the only) provider supported.

State example:

Desired/Current state example (YAML):

- name: eth1
  type: ethernet
  state: up
    enabled: true
    - ip:
      prefix-length: 24
    dhcp: false
    enabled: true
    - ip: 2001:db8:1::a
      prefix-length: 64
    autoconf: false
    dhcp: false
    - 2001:4860:4860::8888
  - destination:
    next-hop-interface: eth1
  - destination: ::/0
    next-hop-address: 2001:db8:1::1
    next-hop-interface: eth1

Basic Operations

Show eth0 current state (python/shell):

import libnmstate

state =
eth0_state = next(ifstate for ifstate in state['interfaces'] if ifstate['name'] == 'eth0')

# Here is the MAC address
eth0_mac = eth0_state['mac-address']
nmstatectl show eth0

Change to desired state (python/shell):

import libnmstate

# Specify a Linux bridge (created if it does not exist).
state = {'interfaces': [{'name': 'br0', 'type': 'linux-bridge', 'state': 'up'}]}
# use yaml or json formats
nmstatectl set desired-state.yml
nmstatectl set desired-state.json

Edit the current state(python/shell):

import libnmstate

state =
eth0_state = next(ifstate for ifstate in state['interfaces'] if ifstate['name'] == 'eth0')

# take eth0 down
eth0_state['state'] = 'down'
# open current state in a text editor, change and save to apply
nmstatectl edit eth3


Nmstate uses the for discussions. To subscribe you can send an email with 'subscribe' in the subject to or visit the mailing list page.

Sprint tracking happens in (Github projects).

There is also #nmstate on Freenode IRC.


Yay! We are happy to accept new contributors to the Nmstate project. Please follow these instructions to contribute.


For Fedora 29+, sudo dnf install nmstate.

For others distribution, please see the install guide.



  • Maximum supported number of interfaces in a single desire state is 1000.


Please refer to CHANGELOG

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for nmstate, version 1.0.3
Filename, size File type Python version Upload date Hashes
Filename, size nmstate-1.0.3-py3-none-any.whl (173.0 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size nmstate-1.0.3.tar.gz (113.1 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page