When your Docker container isn't behaving the way you expect, you need to get inside and see what's going on. Maybe your app is throwing errors, a service won't start, or you just need to check some configuration files.
Getting into a running Docker container is simpler than you might think, but there are several ways to do it depending on your situation. This guide shows you exactly how to log into Docker containers, troubleshoot common issues, and debug your applications effectively.
The Need to Access Docker Containers
Docker containers are designed to be isolated environments, but sometimes you need to inspect what’s happening inside.
Here are the most common reasons developers need container access:
You're debugging an application that behaves differently in the container than it does locally. Maybe configuration files are missing, or something's off with the way it connects to other services. Sometimes, you just need to poke around and run a few commands to figure things out.
Unlike traditional servers, containers usually don’t run SSH daemons. Instead, Docker gives you built-in tools to run commands or open a shell directly inside the container.
The Basic Method: Using docker exec
If you need to poke around inside a running container, docker exec
is the command to use. Here’s the basic syntax:
docker exec -it container_name /bin/bash
Here’s what each part does:
docker exec
tells Docker to run a command inside a running container-i
keeps the input stream open, and-t
allocates a terminalcontainer_name
can be the container’s name or ID/bin/bash
launches the Bash shell (or use/bin/sh
if Bash isn’t available)
Example:
If your web app is running in a container named webapp
, run:
docker exec -it webapp /bin/bash
This opens an interactive shell inside the container, where you can run commands just like you would on any regular Linux machine.
What If Bash Isn’t Installed?
Not every container includes Bash, especially those built on minimal base images like Alpine or scratch
. If you get a “command not found” error, try using sh
instead:
docker exec -it webapp /bin/sh
Need to run just one quick command without opening a shell? That works too:
docker exec webapp ls -la /app
docker exec webapp cat /var/log/app.log
docker exec webapp ps aux
This is a handy option when you’re just checking logs, listing files, or inspecting running processes; no need to jump into a full shell session.
How to Find Your Container Name or ID
Can’t remember what your container’s called? Use these commands to list what’s running:
# Show running containers
docker ps
# Show all containers, including stopped ones
docker ps -a
# Filter by name (e.g., containers with 'web' in the name)
docker ps --filter "name=web"
You can use either the container name or the ID with docker exec
. And good news is, you usually don’t need the full ID. Just the first few characters will do.
What to Do When Your Container Isn’t Runninge
docker exec
only works on containers that are currently running. If your container has stopped, here’s what you can do:
Option 1: Start the Container Again
If the container exists, but you want to inspect it:
docker start webapp
docker exec -it webapp /bin/bash
This restarts the container and lets you jump inside it, just like you would with a running one.
Option 2: Run a Fresh Container from the Same Image
If you just need a clean environment to poke around in:
docker run -it --rm nginx:latest /bin/bash
This spins up a new container from the same image. The --rm
flag removes the container once you exit.
Option 3: Create a Debuggable Image from the Stopped Container
If you want to inspect the exact state of the stopped container:
docker commit webapp debug-image
docker run -it --rm debug-image /bin/bash
This captures the stopped container’s current state as a new image (debug-image
), so you can spin it up and investigate without modifying the original.
What to Do Once You're Inside a Docker Container
Once you're inside a running container, you’ll usually want to confirm whether the app is configured and behaving as expected. Here are common checks and commands developers use when debugging from within a container:
Check Logs
Start by looking at your application's logs—they often hold the first clues when something isn’t working right.
tail -f /var/log/application.log
journalctl -f # if the container uses systemd
These commands show real-time log output so you can watch what’s happening as requests come in or processes fail.
Review Configuration Files
Misconfigurations are a common cause of unexpected behavior. Double-check that config files exist, are readable, and contain the right values.
cat /etc/nginx/nginx.conf
ls -la /app/config/
This helps ensure your app is picking up the correct settings and paths.
Check Running Processes
Sometimes the app isn’t running at all, or there may be zombie processes eating up resources.
ps aux
top
htop # if available
These commands show what’s running and how much CPU/memory each process is using.
Test Network Connectivity
Apps often fail because they can't connect to a dependent service. You can test network routes and endpoints from inside the container:
ping google.com
curl -I http://api.example.com
netstat -tulpn
Use these to confirm DNS resolution, open ports, or response headers from APIs your app relies on.
Check Disk Usage
If your container runs out of disk space, it can silently break logging, caching, or even crash altogether.
df -h
du -sh /var/log/*
These commands show total and per-directory usage so you can identify what's taking up space.
Install Debugging Tools (If Needed)
Minimal containers often lack even basic tools. If you need to poke around more, you can temporarily install utilities—just note these won’t persist unless baked into the image or saved with docker commit
.
apt-get update && apt-get install -y curl vim # Debian/Ubuntu
yum install -y curl vim # CentOS/RHEL
apk add curl vim # Alpine
Advanced Ways to Use docker exec
Once you’re comfortable running commands inside containers, you might run into scenarios where the default docker exec
behavior isn’t enough. Here are some useful flags and combinations to handle more advanced use cases:
Run as a Specific User
By default, docker exec
uses the container’s default user. But sometimes, you need elevated permissions or want to match the app’s runtime user:
docker exec -it -u root webapp bash
docker exec -it -u 1000:1000 webapp bash
Use -u
to specify a user or user:group ID. This is handy when you need access to protected directories or to troubleshoot permission issues.
Set Environment Variables
Need to debug with a feature flag or toggle a mode temporarily?
docker exec -it -e DEBUG=true webapp bash
The -e
flag lets you pass environment variables into the shell session. This is useful when your application reads config from env vars.
Start in a Specific Directory
If you're working in a deeply nested directory, you can start your session there directly:
docker exec -it -w /app webapp bash
The -w
flag sets the working directory inside the container, saving you time navigating folders manually.
Combine Flags for Complex Tasks
You can combine multiple flags to suit your exact needs:
docker exec -it -u root -w /var/log webapp bash
This command launches a shell as the root
user, starting in /var/log
, which is useful when inspecting system-level logs or troubleshooting errors that require elevated access.
Manage Containers via Docker Compose
If you use Docker Compose to manage your containers, accessing them gets simpler. Instead of hunting for container names or IDs, you can directly interact with services using Docker Compose commands. For example, to open a shell inside a service named web
, you’d run:
docker-compose exec web bash
Or to connect to a Postgres database service:
docker-compose exec database psql -U postgres
This approach saves time and reduces mistakes, especially in projects with many containers. It keeps things straightforward by letting you work with service names instead of container IDs.
Important Security Practices for Container Access
But as you jump inside containers to troubleshoot, remember to keep security in mind.
- Containers often run with root privileges, so any changes or added tools can affect app stability and security.
- Document your actions carefully to maintain clear records.
- Whenever possible, replicate issues outside of production to avoid risks.
- For complex problems, use separate debug-ready containers to protect your production environment and simplify troubleshooting.
Alternative Tools and Commands for Container Access
Besides using docker exec
, there are other methods to debug containers:
Copying Files In and Out
Instead of exploring inside the container, you can copy files out for easier analysis, or push scripts and configs in:
docker cp webapp:/app/config.json ./config.json
docker cp ./debug.sh webapp:/tmp/debug.sh
Copying files can be a simpler way to check logs, configs, or run debugging scripts.
Debug Containers
Sometimes, you want to investigate without disturbing the original container. You can run a separate debug container that shares the target container’s process and network namespaces:
docker run -it --rm --pid container:webapp --net container:webapp alpine
This lets you peek inside while keeping the original container safe.
Using docker attach
You can connect directly to a container’s main process with:
docker attach webapp
Be careful when using this — if you exit the session the wrong way, it might stop the container.
Quick Solutions for Common Container Problems
Problem | Solution |
---|---|
Container is not running | Use docker ps -a to check all containers, then start it with docker start container_name |
Executable not found | Try using /bin/sh instead of /bin/bash |
Permission denied | Add -u root to run the command as the root user |
Container exits immediately | Check what’s going wrong with docker logs container_name |
Container keeps stopping
If your container exits immediately after starting, the main process is likely crashing. Use logs to see what’s happening:
docker logs webapp
docker logs --tail 50 webapp
Can’t find the right shell
Different container images come with different shells. Try these in order until one works:
/bin/bash
/bin/sh
/bin/ash
(common in Alpine Linux)/bin/zsh
Need to debug networking?
Run a separate debug container that shares the network namespace of your target container:
docker run -it --rm --network container:webapp nicolaka/netshoot
This gives you handy network tools without changing your app container.
Tips for Effective Container Access
- Keep your debugging focused and always document the steps you take, especially when working in production.
- Whenever possible, try to reproduce problems locally instead of debugging directly on live containers.
- Use container access as just one part of your debugging toolkit. Start by checking logs and metrics, then jump into containers to dig deeper into specific issues.
Create handy shortcuts for common commands to speed up your workflow. For example, add these to your .bashrc
:
alias dsh='docker exec -it $1 /bin/bash'
alias dps='docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"'
Wrapping Up
Jumping into containers can help fix problems, but good observability often spots issues before you even need to log in. At Last9, we offer an easy, affordable platform to monitor your apps without slowing things down, even when handling high-cardinality data.
Companies like Probo, CleverTap, and Replit trust our platform, which brings metrics, logs, and traces together through OpenTelemetry and Prometheus—all in one place, backed by support whenever you need it.
And when you do need to peek inside a container, having that observability info helps you know exactly where to focus your troubleshooting. Get started with us today!
FAQs
How do I get into a running Docker container?
Use docker exec -it container_name /bin/bash
to open an interactive shell. Replace container_name
with your actual container name or ID.
Can I access a stopped Docker container?
No, docker exec
only works with running containers. Start the container with docker start container_name
first, then use docker exec
.
What if my container doesn't have bash?
Try /bin/sh
instead. Most containers have sh
even if they don't include bash
: docker exec -it container_name /bin/sh
How do I run commands as root in a container? Add the -u root
flag: docker exec -it -u root container_name /bin/bash
How can I copy files between my computer and a container?
Use docker cp
: docker cp container_name:/path/to/file ./local/file
or docker cp ./local/file container_name:/path/to/file
What's the difference between docker exec and docker attach?
docker exec
runs a new process in the container, while docker attach
connects to the main process. Use docker exec
for debugging - it's safer.
How do I find my container names?
Run docker ps
to see running containers or docker ps -a
to see all containers including stopped ones.
Why does my container stop when I try to access it?
The main application inside the container has probably crashed. Check the logs with docker logs container_name
to see what went wrong.