Skip to content
Tutorials Center
My learning

Topics

Lesson 8 of 111 ยท Getting Started

Logs and exec

Read container output with docker logs -f --tail, open a shell with docker exec -it, understand docker attach, and copy files in and out with docker cp.

A container is a black box until something goes wrong, and then you need to look inside. Docker gives you four tools for that, and between them they cover almost every "what is it doing?" and "let me try something in there" moment: docker logs shows what the main process has printed, docker exec runs a new command inside a running container (usually a shell), docker attach connects your terminal to the main process, and docker cp copies files between your machine and a container.

These four commands are used constantly in development and in incident response, so it is worth learning their options and their traps. The most common trap is confusing exec and attach; you will see exactly how they differ below.

docker logs: what the container printed

Anything the main process (PID 1) writes to standard output or standard error is captured by Docker and stored by the container's logging driver. This is why containerized programs should log to the console instead of to files: Docker, and later your orchestrator, collects the streams for you.

To experiment, start a container that prints one line to each stream every second:

CONSOLE
$ docker run -d --name demo-ticker alpine sh -c 'i=0; while true; do i=$((i+1)); echo "tick $i"; echo "warn $i" >&2; sleep 1; done'
416beef48690...

Now read its output:

CONSOLE
$ docker logs --tail 4 demo-ticker
tick 7
warn 7
tick 8
warn 8

(The exact lines depend on when you run it.) By default docker logs prints everything the container has produced since it was created, then exits. On a busy container that can be a million lines, so you nearly always want one of these options:

Option Effect
--tail N (or -n N) Only the last N lines. --tail 0 prints nothing but is useful together with -f.
-f / --follow Keep running and print new lines as they arrive, like tail -f. Stop with Ctrl+C.
-t / --timestamps Prefix every line with an RFC 3339 timestamp (UTC, nanosecond precision).
--since 10m Only logs newer than a duration (30s, 10m, 2h) or a timestamp.
--until 10m Only logs older than that.
--details Show extra attributes supplied with --log-opt labels=.../env=.... Rarely needed.

Combine them. The most common form during development is "show me the last few lines and keep following":

CONSOLE
$ docker logs -f --tail 1 demo-ticker
tick 11
tick 12
warn 12
warn 13
tick 13

Press Ctrl+C to leave. That only stops docker logs; the container keeps running.

Standard output vs. standard error

Docker keeps the two streams separate and replays them to the matching streams of your terminal. That has a practical consequence: if you pipe docker logs into another command, only stdout goes through the pipe, and stderr still lands on your screen.

CONSOLE
$ docker logs demo-ticker 2>/dev/null | head -3
tick 1
tick 2
tick 3

Here 2>/dev/null threw away the warn lines. If you want to search all output, merge the streams first:

CONSOLE
$ docker logs demo-web 2>&1 | grep error
2026/10/23 14:15:19 [error] 31#31: *2 open() "/usr/share/nginx/html/missing" failed (2: No such file or directory), client: 172.17.0.1, server: localhost, request: "GET /missing HTTP/1.1", host: "127.0.0.1:8080"

Forgetting 2>&1 is the number-one reason "docker logs shows nothing but the screen is full of text" or "grep finds nothing in the logs". Many programs, including nginx's error log and Python's logging default, write to stderr.

Logs of containers that have stopped

docker logs also works on stopped containers, as long as you have not removed them with docker rm. That is how you find out why a container crashed: the last lines before it died are still there. With docker run --rm the container, and therefore its logs, disappear on exit. Remember that when you debug.

Where the logs live, and the disk-space trap

By default Docker uses the json-file logging driver:

CONSOLE
$ docker inspect -f '{{.HostConfig.LogConfig.Type}}' demo-web
json-file

Each container gets a JSON file on the Docker host, and by default that file grows forever. A chatty service on a long-lived host can fill the disk. You can limit it per container, or for the whole daemon in daemon.json:

CONSOLE
$ docker run -d --name demo-limited --log-opt max-size=10m --log-opt max-file=3 nginx:alpine

This keeps at most three files of 10 MB each. We return to logging drivers, rotation and central log collection in Logging and Monitoring.

With remote logging drivers (such as syslog or awslogs) the full history lives on the remote system. Recent Docker versions keep a small local copy so that docker logs still works, but for anything older you must read the logs where they are stored.

docker exec: run a command in a running container

docker exec starts a new process inside an already running container, sharing its filesystem, network and process namespace. Its basic form is docker exec <container> <command> [args]:

CONSOLE
$ docker exec demo-web nginx -v
nginx version: nginx/1.31.8
$ docker exec demo-web ps
PID   USER     TIME  COMMAND
    1 root      0:00 nginx: master process nginx -g daemon off;
   30 nginx     0:00 nginx: worker process

The ps output also demonstrates the namespace: nginx is PID 1 inside the container, and our ps sees only the container's processes. The command you pass is not run through a shell, so pipes, $VARIABLES and && belong to your shell unless you start a shell on purpose:

CONSOLE
$ docker exec demo-web sh -c 'echo $HOME; whoami; pwd'
/root
root
/

sh -c '...' with single quotes makes the container's shell expand $HOME. Without it, your own shell would expand the variable before Docker ever saw it.

An interactive shell: -it

To get a prompt inside the container, ask for an interactive terminal with -i (keep stdin open) and -t (allocate a pseudo-terminal), almost always written together as -it:

CONSOLE
$ docker exec -it demo-web sh
/ # cat /etc/os-release | head -2
NAME="Alpine Linux"
ID=alpine
/ # exit
$

Typing exit (or Ctrl+D) ends the shell and returns you to your terminal. The container keeps running, because you only terminated the extra process that exec started, not the main one.

Which shell? Use whatever the image contains. Minimal images such as Alpine have sh (BusyBox) but not bash:

CONSOLE
$ docker exec demo-web bash -c 'echo hi'
OCI runtime exec failed: exec failed: unable to start container process: exec: "bash": executable file not found in $PATH

Try sh first. Distroless and scratch images have no shell at all; for those see debugging containers.

Useful options

Option Effect
-u user Run as another user: name or UID. -u 0 is root.
-w dir Working directory for the command (must be absolute).
-e NAME=value Extra environment variable for this command only.
-d Detached: start the command in the background and return at once.
-i without -t Feed stdin to the command, which is how you pipe data in.
CONSOLE
$ docker exec -u nginx demo-web id
uid=101(nginx) gid=101(nginx) groups=101(nginx)
$ docker exec -u 0 demo-web id
uid=0(root) gid=0(root) groups=0(root),1(bin),2(daemon),3(sys),4(adm),6(disk),10(wheel),11(floppy),20(dialout),26(tape),27(video)
$ docker exec -w /etc/nginx demo-web pwd
/etc/nginx
$ docker exec -e FOO=bar demo-web sh -c 'echo $FOO'
bar

Without -u, the command runs as the container's default user. That is the user set by the image (USER in the Dockerfile); here nginx's master process runs as root, so exec gives you root. Stdin works without a terminal, which makes exec good for scripting:

CONSOLE
$ echo "from stdin" | docker exec -i demo-web sh -c 'cat > /tmp/in.txt'
$ docker exec demo-web cat /tmp/in.txt
from stdin

(Leave out -t in scripts and pipes: a pseudo-terminal merges stdout and stderr and mangles line endings.)

Exit codes pass through

docker exec returns the exit code of the command, so it works in shell scripts and health probes. Two special cases come from Docker itself:

CONSOLE
$ docker exec demo-web sh -c 'exit 7'; echo $?
7
$ docker exec demo-web nosuchcmd; echo $?
OCI runtime exec failed: exec failed: unable to start container process: exec: "nosuchcmd": executable file not found in $PATH
127
$ docker exec nope ls; echo $?
Error response from daemon: No such container: nope
1

Exit code 127 means "command not found" (126 would mean "found but not executable"). A container that is not running cannot be entered at all:

CONSOLE
$ docker exec demo-stopped ls
Error response from daemon: container 7c273bdb12fd... is not running

If the main process crashed immediately, start a copy with a different command instead, for example docker run --rm -it --entrypoint sh image (see debugging containers).

Background commands

With -d the command keeps running inside the container, and docker exec returns immediately without output:

CONSOLE
$ docker exec -d demo-web sh -c 'sleep 30'
$ docker top demo-web -o pid,args | tail -1
28804               sleep 30

Everything you start with exec lives and dies with the container. It is not recorded in the image, and it is gone after a restart. Treat exec as a debugging tool, not as a way to configure a container: changes made by hand inside a running container are lost when it is replaced. The right place for a permanent change is the Dockerfile.

docker attach: connect to the main process

docker exec starts something new. docker attach instead connects your terminal to the existing main process (PID 1) and shows its stdin, stdout and stderr:

CONSOLE
$ docker attach --sig-proxy=false demo-ticker
warn 58
tick 58
warn 59
tick 59
^C
$ docker ps --filter name=demo-ticker --format '{{.Status}}'
Up About a minute

You see the live output, like docker logs -f, but without the history. The difference between exec and attach explains many surprises:

docker exec docker attach
What it does Starts a new process in the container Connects to the main process
Typing exit Ends only your new process May end the main process, which stops the container
Ctrl+C Interrupts your new process Is forwarded to the main process unless --sig-proxy=false
Typical use Debug, inspect, run a one-off task Talk to a program that reads stdin (a REPL, a game server console)

When you attach to a container, Ctrl+C is sent to the main process by default and can stop it (the signal is proxied as SIGINT). To leave without disturbing the container, use --sig-proxy=false, or, if the container was started with -it, press the detach sequence Ctrl+P then Ctrl+Q. Do not use attach when you merely want a shell: docker exec -it is the safe choice.

The detach sequence is configurable. docker attach --detach-keys="ctrl-x" (and the same flag on docker run -it and docker exec -it) replaces Ctrl+P, Ctrl+Q for one session. This matters when your terminal, editor or a program inside the container already uses Ctrl+P (previous command in many shells). You can also set a permanent default with "detachKeys": "ctrl-x" in ~/.docker/config.json. A sequence is a comma-separated list of keys, where a control key is written ctrl-<letter>, for example ctrl-x,x.

An example where attach is the right tool: a container started with docker run -dit --name calc python:3-slim python runs a Python REPL in the background. docker attach calc connects you to its >>> prompt, and Ctrl+P, Ctrl+Q leaves it running. Because attach needs the main process to be waiting for input, a normal web server gives you nothing to type into.

docker cp: copy files in and out

docker cp copies files and directories between the host and a container. It works on stopped containers too, which makes it a lifesaver for fetching a crash dump or a config file. The syntax mirrors cp, with container:path marking the container side:

CONSOLE
$ echo "hello from host" > host.txt
$ docker cp host.txt demo-web:/tmp/host.txt
$ docker exec demo-web cat /tmp/host.txt
hello from host
$ docker cp demo-web:/etc/nginx/nginx.conf ./nginx.conf
$ head -5 nginx.conf

user  nginx;
worker_processes  auto;

error_log  /var/log/nginx/error.log notice;

Copying a stopped container's file works the same way (docker cp demo-stopped:/bin/busybox ./bb succeeded above). There is no wildcard support: to copy the contents of a directory, end the source with /.:

CONSOLE
$ docker cp demo-web:/etc/nginx/conf.d ./confd
$ ls confd
default.conf
$ docker cp demo-web:/etc/nginx/conf.d/. ./confd2
$ ls confd2
default.conf

In the first command confd did not exist, so Docker created it from conf.d. If confd had existed, the result would have been confd/conf.d/default.conf, one level deeper. The /. form (second command) always copies the contents. This trailing-slash behavior mirrors cp -r, and it is a classic source of "why is my file one folder too deep?".

Two more details:

  • -a preserves UID/GID information, which matters if the numeric owners differ between host and container. By default files you copy in become owned by root inside the container.
  • Passing - as the path streams a tar archive on stdout or reads one from stdin, which is handy for pipelines: docker cp demo-web:/etc/nginx - | tar -t.

If the path does not exist you get a clear error:

CONSOLE
$ docker cp host.txt demo-web:/nodir/x
Error response from daemon: Could not find the file /nodir in container demo-web

For files you need all the time (configuration, source code, data), docker cp is the wrong tool. Use a bind mount or a volume, and the files are shared automatically instead of copied once.

On Windows with Git Bash, a path such as /etc/nginx can be silently rewritten to C:/Program Files/Git/etc/nginx before Docker sees it. If you get "no such file" errors for paths that obviously exist, run export MSYS_NO_PATHCONV=1 first, or use PowerShell.

A debugging routine

When a container misbehaves, this order solves most problems quickly:

  1. docker ps -a shows whether it is running and its exit code (previous lesson).
  2. docker logs --tail 50 <name> shows the last words of the process.
  3. docker exec -it <name> sh lets you look around: configuration files, environment (env), network (wget -qO- localhost), disk space (df -h).
  4. docker cp fetches files you want to study on the host.
  5. docker inspect answers questions about how the container was configured.

More patterns, including what to do when there is no shell, are in Debugging Containers.

Cleaning up the demo

CONSOLE
$ docker rm -f demo-ticker demo-web demo-stopped
demo-ticker
demo-web
demo-stopped

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. You run 'docker logs web | grep error' but find nothing, although the error is visible when you run 'docker logs web' without the pipe. What is the most likely reason?

    docker logs replays stdout and stderr to the matching streams. A pipe carries only stdout, so use 'docker logs web 2>&1 | grep error'.
  2. 2. Which command shows the last 20 lines of a container's log and then keeps printing new lines?

    --tail N limits the history and -f (--follow) streams new lines. Ctrl+C stops docker logs without stopping the container.
  3. 3. What happens when you type 'exit' in a shell opened with 'docker exec -it web sh'?

    docker exec starts an additional process. Ending it does not affect the main process (PID 1), so the container stays up.
  4. 4. 'docker exec -it app bash' fails with 'executable file not found in $PATH'. What should you try first?

    The image simply does not contain bash. Alpine and many slim images ship BusyBox sh instead; distroless images have no shell at all.
  5. 5. You want to copy the contents of /etc/nginx/conf.d from a container into the existing local folder ./confd without creating a nested conf.d folder. Which source path do you use?

    docker cp does not expand wildcards. Ending the source with /. copies the directory's contents; without it, the directory itself is copied into the target.

Summary

  • docker logs prints what the main process wrote to stdout and stderr; use -f, --tail, --since and -t to follow and narrow it, and 2>&1 before a pipe to include stderr.
  • Logs survive until the container is removed, but with the default json-file driver they grow without limit unless you set max-size and max-file.
  • docker exec runs a new process in a running container: docker exec -it name sh gives you a shell, and -u, -w, -e and -d tune it. It returns the command's exit code (127 when the command is missing).
  • Minimal images may have sh but not bash, and some have no shell at all.
  • docker attach connects to the main process itself; Ctrl+C can stop it, so use --sig-proxy=false or Ctrl+P, Ctrl+Q, and prefer exec for shells.
  • docker cp copies files in either direction, even from stopped containers; end a source directory with /. to copy its contents.
  • Changes made through exec or cp disappear with the container; make them permanent in the image, a volume or a bind mount.

Next: Understanding Images