How to Connect to MongoDB Running in Docker Using a Connection String

The basic connection string for Docker MongoDB

When MongoDB runs inside a Docker container, you connect to it using a MongoDB URI (connection string) that points to the container instead of your local machine. The simplest connection string is mongodb://localhost:27017 if you're running Docker on your own computer and have exposed port 27017. If you're connecting from another container or a different network setup, you'll need to adjust the hostname and port.

The format of a MongoDB URI is always mongodb://[username:password@]hostname:port/database. For Docker, the main difference from a standard local connection is that you may need to use the container's name or IP address instead of localhost, depending on how your Docker network is configured.

Key Takeaways

Use mongodb://localhost:27017 when connecting from your host machine to a MongoDB container that has port 27017 exposed.
Use the container name (like mongodb://mongo:27017) when connecting from another Docker container on the same network.
Add authentication credentials to the URI as mongodb://username:password@hostname:27017/database if your MongoDB instance requires them.
Docker port mapping in your run command (like -p 27017:27017) determines whether localhost will work from your host machine.

Connecting from your host machine

If you started a MongoDB container with a command like docker run -d -p 27017:27017 --name mongo mongodb, the -p 27017:27017 flag maps the container's port 27017 to your host machine's port 27017. This means you can connect using mongodb://localhost:27017 from any application running on your computer.

Test this connection with the MongoDB shell. If you have the MongoDB tools installed locally, run mongosh "mongodb://localhost:27017". If the container is running and the port is exposed correctly, you'll connect successfully. If you get a connection refused error, check that the container is actually running with docker ps and that port 27017 isn't already in use by another process.

Connecting from another Docker container

When you run a second container that needs to reach MongoDB, you have two options: use the container's name or its IP address. If both containers are on the same Docker network (the default bridge network, or a custom network you created), Docker's internal DNS will resolve the MongoDB container's name to its IP address automatically.

For example, if your MongoDB container is named mongo, a second container can connect using mongodb://mongo:27017. This is cleaner than using IP addresses because container IPs can change. If you created a custom Docker network with docker network create mynet and ran both containers with --network mynet, the container name resolution works even more reliably.

If containers are on different networks or you need to use an IP address, find the MongoDB container's IP with docker inspect mongo | grep IPAddress. Then use that IP in your connection string, like mongodb://172.17.0.2:27017. This approach is less flexible because the IP may change if the container restarts.

Adding authentication to your connection string

If you started MongoDB with authentication enabled (for example, with environment variables or a config file that sets up a root user), you must include credentials in your URI. The format is mongodb://username:password@hostname:27017/database.

For instance, if you created a user named admin with password secret123, your connection string would be mongodb://admin:secret123@localhost:27017/admin. The database name at the end (in this case admin) is the authentication database where the user was created, not necessarily the database you want to query.

If your password contains special characters like @, :, or /, you must URL-encode them. For example, pass@word becomes pass%40word. Use an online URL encoder or your programming language's built-in encoding function to avoid connection errors.

Common Docker Compose setup

Many developers use Docker Compose to run MongoDB alongside other services. A typical docker-compose.yml file looks like this:

services: mongo: image: mongo ports: - "27017:27017" environment: MONGO_INITDB_ROOT_USERNAME: admin MONGO_INITDB_ROOT_PASSWORD: password

When you run docker-compose up, the MongoDB service is automatically named mongo and placed on a shared network with any other services in the same Compose file. From another service in the same file, connect using mongodb://admin:password@mongo:27017. From your host machine, use mongodb://admin:password@localhost:27017.

Troubleshooting connection problems

If you can't connect, start by confirming the container is running: docker ps should list your MongoDB container. If it's not there, check the logs with docker logs mongo (replace mongo with your container name) to see why it stopped.

Next, verify the port is exposed. Run docker port mongo to see which ports the container is listening on. If port 27017 isn't listed, you need to stop the container, remove it, and restart it with the -p 27017:27017 flag.

If the container is running and the port is exposed but you still can't connect from your host machine, check whether something else is already using port 27017 on your computer. Run netstat -an | grep 27017 (on Mac or Linux) or netstat -ano | findstr 27017 (on Windows) to see what's listening on that port. If another process is using it, either stop that process or map the container to a different port, like -p 27018:27017, and connect to mongodb://localhost:27018.

Frequently Asked Questions

Why doesn't localhost:27017 work when I try to connect from another container?

Containers have their own network namespace, so localhost inside a container refers to that container itself, not your host machine or other containers. Use the MongoDB container's name instead, like mongodb://mongo:27017, if both containers are on the same Docker network.

Can I use 127.0.0.1 instead of localhost in my connection string?

Yes, mongodb://127.0.0.1:27017 works the same as mongodb://localhost:27017 when connecting from your host machine. However, from another container, neither will work — you must use the container name or its IP address.

What does the error "connection refused" mean?

This usually means the MongoDB container isn't running, the port isn't exposed, or something else is already using that port on your machine. Check that the container is running with docker ps, verify the port with docker port mongo, and confirm nothing else is listening on port 27017.

How do I find the MongoDB container's IP address?

Run docker inspect mongo and look for the IPAddress field in the output. You can also use docker inspect mongo | grep IPAddress to filter just that information. Use this IP in your connection string if you can't use the container name.

Do I need to change the connection string if I restart the container?

If you're connecting from your host machine using localhost, no — the connection string stays the same. If you're connecting from another container using the container name, no — Docker's DNS will find it again. If you're using the container's IP address, yes — the IP may change after a restart, so you'd need to look it up again.

This guide is for general information only and is not medical, financial, legal, or other professional advice. For decisions specific to your situation, consult a qualified professional. See our Editorial Policy.