A Declarative API for Host Network Management

View on GitHub

We are NMState!

A declarative network manager API for hosts.

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.

Visit the demos page and the examples page to see what it can do.

Quick Start Guide


In the first few development cycles, it is recomended to install nmstate from sources.

git clone https://github.com/nmstate/nmstate.git
cd nmstate
pip install --user --upgrade .

Note: In order to report current state, installing nmstate as a non-root user should be enough. For change support, install the package as root.


In order to support specific capabilities, additional packages are required:

View state

The following command will dump the current networking state in json format:

nmstatectl show

    "interfaces": [
            "description": "Production Network",
            "ethernet": {
                "auto-negotiation": true,
                "duplex": "full",
                "speed": 1000
            "ipv4": {
                "address": [
                        "ip": "",
                        "prefix-length": 24
                "enabled": true
            "mtu": 1500,
            "name": "eth3",
            "state": "up",
            "type": "ethernet"

To dump the state in yaml format, use ‘–yaml’ flag:

nmstatectl show --yaml

- description: Production Network
    auto-negotiation: true
    duplex: full
    speed: 1000
    - ip:
      prefix-length: 24
    enabled: true
  mtu: 1500
  name: eth3
  state: up
  type: ethernet

Change state


Want to see nmstate in action? Check out the demos.

Supported Interfaces:

Stack support: