Docker networks

Don't use the constructor directly. Instead use

from python_on_whales import docker

my_network = docker.network.create("some-network")

my_network = docker.container.inspect("some-network")

For type hints, use this

from python_on_whales import Network, docker

def ping_hostname_in_network(my_network: Network):
    docker.run("busybox", ["ping", "-c", "10", "my_hostname"], networks=[my_network])

Attributes

It attributes are the same that you get with the command line: docker network inspect ...

If you want to know the exact structure, you can go to the docker network inspect reference page and click on "200 no error". An example is worth many lines of descriptions.

In [1]: from python_on_whales import docker

In [2]: network = docker.network.create("my-network")

In [3]: container = docker.run(
            "ubuntu", ["sleep", "infinity"], name="my_ubuntu", detach=True, networks=[network]
        )

In [4]: def super_print(obj):
   ...:     print(f"type={type(obj)}, value={obj}")
   ...:

In [5]: super_print(network.name)
type = <class 'str'>, value = my-network

In [6]: super_print(network.id)
type = <class 'str'>, value = 9414659cd84925fbd8010f171be97225145ba93437f86f47a28720037ac3ebd1

In [7]: super_print(network.created)
type = <class 'datetime.datetime'>, value = 2025-01-10 19:26:52.920031+00:00

In [8]: super_print(network.scope)
type = <class 'str'>, value = local

In [9]: super_print(network.driver)
type = <class 'str'>, value = bridge

In [10]: super_print(network.enable_ipv6)
type = <class 'bool'>, value = False

In [11]: super_print(network.ipam.driver)
type = <class 'str'>, value = default

In [12]: super_print(network.ipam.config)
type = <class 'list'>, value = [{'Subnet': '172.19.0.0/16', 'Gateway': '172.19.0.1'}]

In [13]: super_print(network.ipam.options)
type = <class 'dict'>, value = {}

In [14]: super_print(network.internal)
type = <class 'bool'>, value = False

In [15]: super_print(network.attachable)
type = <class 'bool'>, value = False

In [16]: super_print(network.ingress)
type = <class 'bool'>, value = False

In [17]: super_print(network.containers)
type = <class 'dict'>, value = {'4695dbf05087d5cf453315556c04cad63eb5f1917b2e19b78dfebbc27523052a': NetworkContainer(name='my_ubuntu', endpoint_id='b97f463c927dd451314d56b54f4bf86f1203f3c54d7bda82affa39b08187ae8e', mac_address='02:42:ac:13:00:02', ipv4_address='172.19.0.2/16', ipv6_address='')}

In [18]: super_print(network.options)
type = <class 'dict'>, value = {}

In [19]: super_print(network.labels)
type = <class 'dict'>, value = {}

In [20]: super_print(network.config_from)
type = <class 'dict'>, value = {'Network': ''}

In [21]: super_print(network.config_only)
type = <class 'bool'>, value = False

Methods

Network

exists

exists()

Returns True if the network exists and False if it doesn't exist.

If it doesn't exist, that most likely means it was removed.

remove

remove()

Removes this Docker network.

Rather than removing it manually, you can use a context manager to make sure the network is deleted even if an exception is raised.

from python_on_whales import docker

with docker.network.create("some_name") as my_net:
    docker.run(
        "busybox",
        ["ping", "idonotexistatall.com"],
        networks=[my_net],
        remove=True,
    )
    # an exception will be raised because the container will fail
    # but the network will be removed anyway.