1. Overview

When launching Docker containers, we may sometimes encounter the “name already in use by container” error.

In this short tutorial, we’ll look at this common problem, which is easy to fix. 

First, we’ll show how to cause this errorThen, we’ll explain the reason for it. Finally, we’ll show how to fix it.

2. How to Cause the Error

2.1. Getting a Docker Image

Let’s first choose a Docker image for our example.

We are going to use the free and publicly available Nginx demo image. NGINX is a free and open-source web server used by many companies like NetflixCloudFare, and Airbnb. The Docker demo image that we’re going to use serves a web page with a few basic properties such as the hostname, IP address, and port.

2.2. Running Multiple Containers and Causing the Error

In order to cause the error, we need to run two instances that will use the same name, baeldung_nginx.

It’s worth considering why we even need a name for a container. Names can be a handy way to add meaning to the list of running containers. What’s more, the name can be used as a reference in the Docker network.

Let’s start the first container:

docker run --name baeldung_nginx -p 80:80 -d nginxdemos/hello:plain-text

We’re running the container in a detached mode, which means that it will run in the background. We’re publishing the container’s port 80 to the same port on the host machine. Lastly, we’ve specified our custom name for the container – baeldung_nginx.

Now, if we open http://localhost in our browser, we should see something similar to this:

Server address:
Server name: e378ad49d49d
Date: 08/Apr/2022:22:08:44 +0000
URI: /
Request ID: 7bda7e3234cb6d1e51900fccc89320d5

Let’s now try running a second container. We’ll assign port 81 for the second instance because host port 80 is already taken by the first container:

docker run --name baeldung_nginx -p 81:80 -d nginxdemos/hello:plain-text

Unfortunately, this doesn’t work. We get an error:

docker: Error response from daemon: Conflict. The container name "/baeldung_nginx" is already in use by container "76da8f6d3accc9b6d41c8a98fd492d4b8622804220ee628a438264b8cf4ae3d4". 
You have to remove (or rename) that container to be able to reuse that name.
See 'docker run --help'.

3. Explaining the Root Cause of the Error

Every Docker container has a unique name assigned to it. If we don’t use the optional name argument in the docker run command, Docker assigns a random name.

In our case, we wanted to assign the same name, baeldung_nginx, to two different containers. We should note that even though we’re using the same Docker image, each docker run command creates a new container.

As the second container could not use a name already in use, we got the error.

4. How to Fix It

4.1. Restarting the Container

This solution applies to the case where the Docker container named baeldung_nginx already exists in the system, and that’s the correct state. In this case, we don’t want to have two different instances with the same name. Instead, we want to restart the already existing container.

In order to restart the existing container, we must use the docker start instead of the docker run command. 

docker run creates a new container of an image. We can create as many clones of the same image as possible. On the other hand, docker start launches a previously stopped container.

So, we may not be trying to start a new container so much as restart the existing one, in which case this is the solution. However, sometimes we want to launch a replacement for the existing container with a new image.

4.2. Removing Existing Container

When we are sure that we want our new container to take over the name, and we have stopped any other container with this name, we can simply remove the previous container with the name:

docker rm baeldung_nginx

Unfortunately, this command doesn’t always work. For example, other containers may need our container to work correctly. If that’s the case and we still want to remove our container, we can use the force flag in the remove command:

docker rm -f baeldung_nginx

Once the previous container has been removed, we’re free to launch a new container with our chosen name.

4.3. Using Different Names for Containers

What if we want to run two instances of the same image? The solution for this case is straightforward. All we have to do is use two different names as well as ports:

docker run --name baeldung_nginx_1 -p 80:80 -d nginxdemos/hello:plain-text
docker run --name baeldung_nginx_2 -p 81:80 -d nginxdemos/hello:plain-text

Now, let’s use the following Docker command to list running containers:

docker ps

We should see something similar to this:

CONTAINER ID   IMAGE                         COMMAND                  CREATED          STATUS          PORTS                NAMES
f341bb9fe165   nginxdemos/hello:plain-text   "/docker-entrypoint.…"   2 seconds ago    Up 2 seconds>80/tcp   baeldung_nginx_2
33883c2b31a7   nginxdemos/hello:plain-text   "/docker-entrypoint.…"   12 seconds ago   Up 11 seconds>80/tcp   baeldung_nginx_1

5. Conclusion

In this article, we learned how to fix “name already in use by container” error in Docker.

First, we saw how to reproduce the error. Then, we looked at the root cause of the error.

Finally, we saw three different solutions for fixing the issue.

Comments are open for 30 days after publishing a post. For any issues past this date, use the Contact form on the site.