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.

Security warning: Most examples are ordinary Docker commands, but they may still need membership of the Docker group or elevated access to the Docker socket. Do not add sudo automatically, because access to Docker is effectively administrative access on the host.

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}}'

Checkpoint: docker network inspect succeeds, and the container inspect command prints the container name. If the network does not exist, stop here and create or select the intended network through your normal deployment workflow. Do not connect a production container to a guessed network.

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.

Warning: Connecting a container to a second network can change how it reaches other services and can change the default gateway. Treat that as a service-impacting change. If the container carries public traffic, use a maintenance window or a tested rollback path.

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}}

Checkpoint: You can see the network key, an endpoint and an IP address. The IDs, MAC address, IP address and subnet vary, so do not copy them as fixed output.

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.

Tip: If the container is already attached, do not repeat docker network connect just to add an alias. Record the current settings, disconnect during an appropriate maintenance window, then reconnect once with the complete set of required options.

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.

Warning: An address that is unavailable causes the connect operation to fail, while a static address that becomes unavailable can prevent the container from restarting.

Tip: If you need stable static assignments, create the network with an --ip-range that excludes the addresses reserved for static containers. That planning belongs when the network is created. Do not change a busy network's IPAM settings as an improvised repair.

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.

Tip: Verify the resulting routing behaviour from inside the container if outbound traffic matters. A successful connect command alone does not prove that an application will use the route you intended.

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}}'

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.

Recovery: Reconnect the container with the same --alias, --ip, --ip6 and gateway settings if those settings are still required.

Done means