How to Connect to MongoDB Running in Docker on Your Local Machine

What you're actually doing when you connect to localhost MongoDB in Docker

When you run MongoDB inside a Docker container, it's isolated from your computer's main system — it lives in its own walled-off environment. To reach it from your code or tools, you need to tell Docker to create a bridge between your machine and the container, then use a connection string (called a MongoDB URI) that points to that bridge. The URI is just a formatted address that says "go to this location, using this username and password, and connect to this database."

Most people get stuck because they try to use localhost:27017 (the default MongoDB port) the same way they would for a program running directly on their machine. In Docker, that doesn't work — you have to either expose the port when you start the container, or use Docker's internal networking if your code is also running in a container.

Key Takeaways

Docker containers need the -p 27017:27017 flag when you start them so your computer can reach MongoDB on port 27017.
A MongoDB URI for localhost looks like mongodb://username:password@localhost:27017/databasename, but only works if the port is exposed.
If your code is also in a Docker container, use the container's name instead of localhost — for example, mongodb://mongo:27017.
Docker Compose handles port exposure and networking automatically, so you don't have to remember flags for each container.
Test your connection with a straightforward MongoDB client tool before running your full process.

Starting MongoDB in Docker with port exposure

The command to run MongoDB in Docker looks like this:

docker run -d -p 27017:27017 --name mongo mongo:latest

Break down what each part does: docker run starts a new container. The -d flag runs it in the background so your terminal stays free. -p 27017:27017 exposes the port — the first number is the port on your computer, the second is the port inside the container. --name mongo gives the container a name you can reference later. mongo:latest is the image to use (the official MongoDB image).

After you run this command, MongoDB is listening on your machine at localhost:27017. You can now connect to it from any tool or code running on your computer.

Building the correct MongoDB URI for localhost

A MongoDB connection string has this structure:

mongodb://[username]:[password]@[host]:[port]/[database]

For a local Docker container with no authentication set up yet, the simplest URI is:

mongodb://localhost:27017/myapp

Replace myapp with whatever you want to call your database. If you set a username and password when you started the container (or in your Docker Compose file), add them like this:

mongodb://myuser:mypassword@localhost:27017/myapp

Some applications expect the URI in an environment variable called MONGODB_URI or MONGO_URL. Check your process's documentation to see where it looks for this string.

Using Docker Compose to manage MongoDB and your process

Docker Compose is a tool that runs multiple containers together and handles networking for you. Create a file called docker-compose.yml in your project folder with this content:

version: '3'services: mongo: image: mongo:latest ports: - "27017:27017" environment: MONGO_INITDB_ROOT_USERNAME: myuser MONGO_INITDB_ROOT_PASSWORD: mypassword app: build: . ports: - "3000:3000" environment: MONGODB_URI: mongodb://myuser:mypassword@mongo:27017/myapp depends_on: - mongo

This file defines two services: mongo (the database) and app (your process). The key difference from running Docker manually is the MONGODB_URI — it uses mongo (the service name) instead of localhost. Docker Compose creates an internal network where containers can reach each other by name. The depends_on line tells Docker to start MongoDB before your app.

Start everything with:

docker-compose up

Connecting from code running on your computer (not in Docker)

If your process code is running directly on your machine — not inside a container — use the localhost URI:

mongodb://localhost:27017/myapp

This works only if you started the MongoDB container with -p 27017:27017. Test the connection with the MongoDB shell. First, check that the container is running:

docker ps

Then connect to it:

docker exec -it mongo mongosh --authenticationDatabase admin -u myuser -p mypassword

If you see a MongoDB prompt, the container is working and accepting connections. If you get a connection refused error, the port is not exposed — stop the container and restart it with the -p flag.

Connecting from code inside another Docker container

If your process is also running in a Docker container, do not use localhost. Instead, use the MongoDB container's name:

mongodb://mongo:27017/myapp

This only works if both containers are on the same Docker network. If you use Docker Compose, they're automatically on the same network. If you're running containers separately with docker run, create a network first:

docker network create mynetworkdocker run -d --network mynetwork --name mongo mongo:latestdocker run -d --network mynetwork --name app myapp:latest

Now your app container can reach the mongo container by name. The port does not need to be exposed with -p when containers are on the same network — they communicate directly.

Troubleshooting connection problems

If your connection fails, check these things in order. First, verify the container is running:

docker ps

If MongoDB is not listed, start it. If it is listed but your connection still fails, check the logs:

docker logs mongo

Look for error messages about port binding or authentication. If you see "bind: address already in use", another program is using port 27017 — either stop that program or use a different port (for example, -p 27018:27017 to use port 27018 on your machine).

If you're using authentication, make sure your username, password, and database name in the URI match exactly what you set in the container. Spaces and special characters matter. If you're connecting from code in another container, use the container name, not localhost. If you're connecting from your machine, use localhost and make sure the port is exposed with -p.

Frequently Asked Questions

What's the difference between localhost and the container name?

Localhost means "this computer" — it only works from your machine or from code running directly on your machine. A container name is an address inside Docker's network — it only works from other containers on the same Docker network. If your code is in a container and you use localhost, it will try to find MongoDB on that container's own system, not on your machine.

Do I have to use port 27017?

No. You can use any port on your machine. If 27017 is already in use, run docker run -p 27018:27017 --name mongo mongo:latest to use port 27018 on your machine while MongoDB listens on 27017 inside the container. Then connect to localhost:27018.

What if I don't want to set a username and password?

You can run MongoDB without authentication for local development, but it's not recommended. If you do, start it with docker run -d -p 27017:27017 mongo:latest and connect with mongodb://localhost:27017/myapp. For production or shared machines, always use authentication.

How do I stop the MongoDB container?

Run docker stop mongo to stop it gracefully, or docker rm mongo to remove it entirely. If you used Docker Compose, run docker-compose down from the folder with your docker-compose.yml file.

Can I see the data stored in the container?

By default, data is deleted when you remove the container. To keep data between restarts, add a volume to your docker run command: docker run -d -p 27017:27017 -v mongo_data:/data/db --name mongo mongo:latest. This stores data in a Docker volume called mongo_data that persists even after the container stops.

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.