Create and Verify a Docker Network Without Losing Track of Its Scope

You will create a user-defined Docker bridge network, check the subnet and gateway Docker assigned, and remove the network cleanly afterwards. The same workflow gives you a safe starting point for connecting application containers by name.

Before you start

You need Docker Engine and permission to talk to its daemon. Creating a network normally does not require a root shell, but a user who cannot access the Docker socket may need an administrator to grant access or to run the command. Do not add sudo automatically: it can make files and later Docker commands use a different user context.

Allow about five minutes for this walkthrough. The examples use Docker Engine 29.8.1, installed here from the docker-ce-cli package. Check your own client and server before relying on version-specific behaviour:

docker version
docker network create --help

The client and daemon must both be available. The command accepts one network name, and names should be unique on the Docker host.

Checkpoint 1: create a user-defined bridge

A bridge network is local to one Docker Engine. It is the normal choice when containers on one host need an isolated network. The driver defaults to bridge, but stating it explicitly makes the example easier to review.

Choose a subnet that does not overlap with the host, VPNs, office network or other Docker networks. This example uses a private range reserved only for the test network:

docker network create \
  --driver bridge \
  --subnet 172.30.240.0/24 \
  --gateway 172.30.240.1 \
  project-net

On success, Docker prints a long network ID, for example:

6c31b216ef527ea612289b559baf74c768c38e86bfd030e509954c71ea854320

If Docker reports that the name already exists, inspect the existing network before deciding whether it is yours. Do not blindly reuse a name from another project.

Checkpoint 2: inspect what Docker created

Creation succeeding does not prove that the network has the addressing you intended. Inspect it before attaching services:

docker network inspect project-net

For a compact check of the important fields, use:

docker network inspect \
  --format '{{.Name}} {{.Driver}} {{.Scope}} {{range .IPAM.Config}}{{.Subnet}} {{.Gateway}}{{end}}' \
  project-net

Expected values include the name project-net, driver bridge, scope local, subnet 172.30.240.0/24 and gateway 172.30.240.1. Inspect output is the useful authority when Docker chooses defaults, such as a gateway omitted from the command.

Checkpoint 3: attach containers by network name

Start a container with --network when it is created. This example uses two short-lived Alpine containers, so it does not leave a running service behind:

docker run -d --name project-one --network project-net alpine sleep 300
docker run -d --name project-two --network project-net alpine sleep 300

Verify that both containers are connected:

docker network inspect \
  --format '{{range .Containers}}{{.Name}} {{end}}' \
  project-net

The output should include project-one and project-two. User-defined networks provide Docker DNS, so a container can address another by its container name. That name resolution is scoped to the network: a container on another network is not automatically a peer.

Stop and remove the examples when you have finished testing:

docker rm --force project-one project-two

This is a destructive command for those two containers. It removes them and stops them if necessary. It does not remove images or the network.

Choose advanced options deliberately

--subnet sets the network segment, --gateway sets its gateway, and --ip-range limits container address allocation to a sub-range. A bridge network accepts one subnet. Docker can select a non-overlapping subnet and a gateway when you omit these flags, but implicit choices can collide with a later VPN or a second project. Pin them when repeatability matters.

Use --internal when containers should communicate with each other but the network should not provide ordinary external connectivity. Treat this as a connectivity boundary, not as a complete security policy: applications, published ports and host access still need their own review.

Driver options belong after --opt. For example, this sets the default host address used when a bridge network publishes container ports:

docker network create \
  --driver bridge \
  --opt com.docker.network.bridge.host_binding_ipv4=127.0.0.1 \
  local-only-published-ports

Check the resulting network with docker network inspect local-only-published-ports. Do not copy driver options from a different driver without checking that driver's documentation.

When an overlay network is the right answer

Do not choose overlay merely because it sounds more capable. It is for networks spanning Docker daemons, and the hosts must be in Swarm mode. Standalone containers on different hosts also require Swarm mode. The participating hosts need the documented Swarm and overlay traffic ports open.

On a Swarm manager, a basic service network is:

docker network create --driver overlay project-overlay

By default, a Swarm-scoped overlay is for services. Add --attachable only when manually started containers must join it:

docker network create \
  --driver overlay \
  --attachable \
  project-overlay

Overlay networks use distributed networking, so subnet planning matters. Docker's current guidance is to keep the default /24 block for VIP-based endpoint mode and use multiple smaller networks or DNS round-robin with an external load balancer when the design needs more addresses.

Undo the test network

Before removal, check which containers are attached:

docker network inspect project-net

Removing a network disconnects attached containers and can interrupt services. Stop or disconnect those workloads first, then remove the network:

docker network rm project-net

Docker prints the removed network name. If removal fails because containers are still connected, identify them from docker network inspect and use docker network disconnect project-net CONTAINER only when that change is safe. The built-in default bridge network is different: Docker creates it for the daemon and it cannot be removed with this command.