Add a Running Container to a Network with docker network connect

The container is live, it needs to talk to a service on another network, and you would rather not restart it, so use docker network connect. You will attach an existing container to a Docker network, confirm the attachment, and detach it again if you no longer need it. Allow about fifteen minutes, including a short verification run.

The examples use Docker 29.8.1 from the installed docker-ce-cli package. You need Docker Engine access, an existing network and an existing container.

1. Check the names before changing anything

List the networks and containers first. This is read-only and prevents a common slip: mistaking a network name, container name or short ID for another object.

$ docker network ls
$ docker ps --all --format 'table {{.Names}}\t{{.Status}}'

Set placeholders only after you have matched them to the output:

NETWORK_NAME='backend-net'
CONTAINER_NAME='api-container'
docker network inspect "$NETWORK_NAME"
docker inspect "$CONTAINER_NAME" --format '{{.Name}}'

2. Connect the container

Use the network first and the container second. The container may be named by name or ID and does not need to be stopped for this operation:

$ docker network connect "$NETWORK_NAME" "$CONTAINER_NAME"

A successful command normally prints nothing and returns status 0. The attachment is network-scoped: it adds an interface and network settings for this network without removing the container's existing networks.

Verify the network's container list and the container's network settings:

$ docker network inspect "$NETWORK_NAME" --format '{{json .Containers}}'
{"container-id":{"Name":"api-container","EndpointID":"endpoint-id","MacAddress":"02:42:ac:1f:00:0a","IPv4Address":"172.31.0.10/16","IPv6Address":""}}

$ docker inspect "$CONTAINER_NAME" --format '{{json .NetworkSettings.Networks}}'
{"backend-net":{"IPAMConfig":null,"Links":null,"Aliases":["api-container"],"DriverOpts":{},"GwPriority":0,"NetworkID":"network-id","EndpointID":"endpoint-id","Gateway":"172.31.0.1","IPAddress":"172.31.0.10","IPPrefixLen":16}}

3. Add an alias when you make the attachment

An alias gives the container another name on this network. It does not rename the container globally, and it does not create a DNS record outside Docker's network scope. If you have not connected the container yet, use this command instead of the basic command in step 2:

$ docker network connect --alias api-readonly "$NETWORK_NAME" "$CONTAINER_NAME"

You can supply --alias more than once. Use a name that is unambiguous to the clients on this network, and check the result:

$ docker inspect "$CONTAINER_NAME" --format '{{json (index .NetworkSettings.Networks "backend-net").Aliases}}'
["api-container","api-readonly"]

Replace backend-net in the format expression with the actual network name. If the network name contains characters that make a Go template awkward, use the full JSON output and inspect the corresponding object instead.

4. Request a fixed address only when the network supports it

Docker normally assigns an address from the network's IPAM pool. A static address is a configuration decision, not a cosmetic preference. First inspect the network's subnet and current allocations:

$ docker network inspect "$NETWORK_NAME" --format '{{json .IPAM.Config}}'
[{"Subnet":"172.31.0.0/16","Gateway":"172.31.0.1"}]

If the address is inside that subnet and is reserved for this container, include --ip in the initial connection, instead of using the basic command in step 2:

$ docker network connect --ip 172.31.10.25 "$NETWORK_NAME" "$CONTAINER_NAME"

For IPv6, use --ip6 and an address from the network's IPv6 subnet. Do not invent a subnet or reuse an address from another container.

5. Choose the default gateway deliberately

A container attached to several networks can have more than one possible route out. Docker uses gateway priority to choose the default gateway. The highest value wins, and the default priority is 0. Use this form instead of the basic connection when this network should be preferred:

$ docker network connect --gw-priority 1 "$NETWORK_NAME" "$CONTAINER_NAME"
$ docker inspect "$CONTAINER_NAME" --format '{{json .NetworkSettings.Networks}}'

Use a positive value only when this network should be the container's preferred default route. A negative value can make a network less preferred. The command above is an alternative form of the initial connection, not a second connection to an endpoint that already exists.

6. Handle failures without guessing

If Docker says the network or container cannot be found, rerun the listing commands and check spelling, project prefixes and whether you are talking to the expected Docker context:

$ docker context show
$ docker network ls
$ docker ps --all --format '{{.ID}} {{.Names}} {{.Status}}'

• Endpoint already exists. This usually means the container is already connected. Inspect it rather than repeatedly retrying.
• Requested IP fails. It may be outside the subnet, already allocated, or unsupported by the selected network driver.
• Driver option rejected. The driver can refuse it; --driver-opt is not a general-purpose switch.
• Legacy --link. It is available in the installed command, but it is not a substitute for a user-defined network and service discovery. Prefer network aliases and normal container DNS for new configurations.

7. Disconnect and recover

Disconnecting is the undo operation for this attachment. It is also service-impacting: processes in the container may immediately lose access to peers on that network. Confirm the target network twice before running it.

$ docker network inspect "$NETWORK_NAME" --format '{{json .Containers}}'
$ docker network disconnect "$NETWORK_NAME" "$CONTAINER_NAME"
$ docker network inspect "$NETWORK_NAME" --format '{{json .Containers}}'
{}

Disconnecting does not remove the container or delete the network. It removes only that container's endpoint from that network. If the container was connected to other networks, those attachments remain.