How do I create a Docker network for docker-compose?

Run: docker network create my-network. Then in docker-compose.yml, declare it as external: networks: { my-network: { external: true } }. The network name in the yml must match the name you created. Verify with: docker network ls.

What is the Docker Compose project name prefix?

Docker Compose prefixes all resources (networks, volumes, containers) with the project name. The default project name is the directory name. So if your directory is "myapp" and you define a network called "backend", Docker creates "myapp_backend". If another compose file references "backend" as external, it won't find it unless it uses the full name "myapp_backend" or shares the same project name.

Docker & Containers

Fix Docker Compose "Network Not Found" Error

The network not found error means Docker Compose is looking for a network that doesn't exist. Here's how to find the cause and fix it.

Quick Fix (3 steps)

1. List existing networks: docker network ls
2. Create the missing network: docker network create NETWORK_NAME
3. Run docker compose up again

What the Error Looks Like

ERROR: network myapp_backend declared as external, but could

not be found. Please create the network manually using

"docker network create myapp_backend" and try again.

This error appears when your docker-compose.yml declares a network as external: true but that network doesn't exist in Docker. Docker Compose will not create external networks for you.

Common Causes

Cause 1: External Network Not Created

The most common cause — you declared external but forgot to create it

# docker-compose.yml

networks:

shared-net:

external: true ← network must exist

# Fix: create the network first
docker network create shared-net

# Verify it exists
docker network ls | grep shared-net

# Then run compose
docker compose up -d

Cause 2: Project Name Prefix Mismatch

Docker Compose prefixes network names with the project name

By default, Docker Compose uses the directory name as the project name. If your directory is my-project/, a network called backend becomes my-project_backend.

# Check what networks actually exist
docker network ls
# You might see: myapp_backend (not just "backend")

# Fix option 1: use the full name in docker-compose.yml
networks:
  backend:
    external: true
    name: myapp_backend  # ← explicit full name

# Fix option 2: set the project name to match
# docker compose -p myapp up -d

Cause 3: Typo in Network Name

A simple typo between the network definition and its usage

Typo

networks:

backned: ← typo

external: true

Fixed

networks:

backend: ← correct

external: true

Cause 4: Zombie Network from Previous Compose Project

A previous project created the network, but it was cleaned up

# List all networks (including unused ones)
docker network ls

# Remove zombie networks
docker network prune

# Recreate the network you need
docker network create my-network

Tip: docker network prune removes all unused networks. This is safe — Docker won't remove networks that are in use by running containers.

Cause 5: Different Docker Context

You created the network in one Docker context but are running Compose in another

# Check your current Docker context
docker context ls

# Switch to the correct context
docker context use default

# Or specify the context explicitly
DOCKER_HOST=unix:///var/run/docker.sock docker compose up -d

This happens if you use Docker Desktop, WSL2, or remote Docker hosts. The network exists in one context but not the other.

Proper Network Configuration

Single Project with Internal Network

For a single docker-compose.yml, use internal networks (no external needed):

# docker-compose.yml
services:
  web:
    image: nginx
    networks:
      - frontend

  api:
    image: node
    networks:
      - frontend
      - backend

  db:
    image: postgres
    networks:
      - backend

networks:
  frontend:   # Docker creates these automatically
  backend:    # No "external: true" needed

Multiple Projects Sharing a Network

When two docker-compose.yml files need to communicate:

# Step 1: Create the shared network
docker network create shared-net

# Step 2: docker-compose.yml (Project A)
services:
  web:
    image: nginx
    networks:
      - shared-net

networks:
  shared-net:
    external: true

# Step 3: docker-compose.yml (Project B)
services:
  api:
    image: node
    networks:
      - shared-net

networks:
  shared-net:
    external: true

Using the `name` Property

The name property lets you control the exact Docker network name, independent of the project name prefix:

networks:
  backend:
    name: my-backend-network  # ← exact name in Docker
    external: true

Frequently Asked Questions

Why does Docker Compose say "network not found"?

The most common cause is declaring a network as "external: true" in docker-compose.yml but the network doesn't exist in Docker. Docker Compose will not create external networks — you must create them manually with "docker network create". Other causes: the network exists but with a different project name prefix, or you're in a different Docker context.

How do I share a network between two Docker Compose projects?

Create a shared network manually: docker network create shared-net. Then in both docker-compose.yml files, declare it as external with the same name: networks: { shared-net: { external: true } }. Both projects can now communicate on the shared network.

What is the difference between internal and external networks in Docker Compose?

Internal networks are created and managed by Docker Compose — they are automatically created on "docker compose up" and removed on "docker compose down". External networks must exist before you run Compose — they are not created or removed by Compose. Use internal for single-project isolation, external for multi-project communication.

How do I clean up unused Docker networks?

Run "docker network prune" to remove all unused networks. This is safe — Docker won't remove networks attached to running containers. To remove a specific network: "docker network rm NETWORK_NAME". To see which networks are unused: "docker network ls" and look for networks not attached to any container.

Key Takeaways

External networks must be created manually before running docker compose up.
Docker Compose prefixes network names with the project name (directory name by default).
Use docker network ls to see what networks exist and docker network create to create missing ones.
Use the name property to control exact network names and avoid prefix confusion.
For single projects, use internal networks (no external: true) — Docker Compose manages them automatically.