Skip to content

Docker Containers Are Just Linux: How Docker Works From First Principles

A 41 MB Ubuntu image runs a whole Linux on your laptop, and you can start hundreds of them. Are you running 100 Ubuntus? And why is it so small?

Prefer to watch? This post is the written companion to the video above.

Open your terminal and run the "hello world" of containers:

docker run -it ubuntu

A second later you are sitting in a root shell, and it looks like a whole Ubuntu is running inside your laptop. The ubuntu:latest image behind it is about 41 MB.

Now start another one. And another. You can run hundreds of these side by side on one machine. So are you running 100 copies of Ubuntu on your laptop?

Obviously not. Your laptop would never boot 100 operating systems. And yet each container really does behave like its own Linux machine. You can run a JVM application in one, a few Python uvicorn workers in another, a database in a third, pretty much anything.

So how does a whole working Linux fit in 41 MB? The Ubuntu 26.04 server ISO is 2.7 GB and the desktop ISO is 6.1 GB. Same Ubuntu, about 100 times smaller. And the slim and minimal images people use in production are smaller still, partly on purpose: fewer files means fewer things an attacker can use.

Here is one more clue. Inside that Ubuntu container, make a folder, write a file, cat it. Works. Now open it in an editor: nano a.txt. Command not found. vi a.txt. Also not found.

So whatever this is, it is not a full operating system. What is it then?

The puzzle: a 41 MB image gives you something that looks like a whole Ubuntu, while the install ISOs are 2.7 GB and 6.1 GB. And there is no nano and no vi.

I walk through this whole idea in the video at the top of this page. The post follows the same path.

Two questions

Everything about containers comes down to two questions:

  1. What is actually inside an image?
  2. How does my machine run that image so it looks like a separate computer?

We will answer them in this order, from first principles, and by the end docker run will not feel like magic.

The two questions this post answers, in order: what is inside an image, and how the machine runs it as if it were a separate computer.

Question 1: what is inside an image

Start with what you can see. Suppose you run the container and list its root folder:

docker run -it ubuntu
ls /
# bin   boot  dev   etc   home  lib   lib64  media  mnt  opt
# proc  root  run   sbin  srv   sys   tmp    usr    var

That is the familiar layout of any Linux machine. cd /bin and you find cp, ls, bash. But this cp is not your laptop's cp. It came out of the image.

So let's cut open the image and see what's inside.

What an image carries (a root filesystem, a manifest and a config) and what it leaves out: kernel, drivers, boot code, init system, desktop and editors.

Now connect it back to the ls / output. Those folders are the image's root filesystem: /bin, /sbin, /lib and /usr hold the binaries and libraries, /etc holds config files such as /etc/hosts and /etc/hostname, and /proc and /sys are empty folders waiting to be filled in when the container runs. Next to that folder tree, an image carries two small JSON files. A manifest lists the layers the filesystem is built from. A config says how to start it: environment variables, the working directory, the default command or entrypoint, the user to run as, volumes, exposed ports and a health check.

from video content

The inside of an image, box by box: the root filesystem folders on top, then the manifest and config with everything the config tells the runtime.

What matters even more is what an image does NOT carry:

  • No Linux kernel. The kernel is the part of the OS that talks to hardware, schedules processes and handles system calls. The image has none of it.
  • No device drivers. The keyboard, the network card, the disk. Not in there.
  • No hardware-specific code. No boot loader, no firmware.
  • No init system. A normal Ubuntu boots systemd as process 1, which then starts services. A container has no boot. The command you start becomes process 1.
  • No desktop, no editors, no media players. That is why nano and vi were missing.
from video content

What an image leaves out. All of these layers are in the Ubuntu ISO; the kernel comes from the host.

All of those things are what make an install ISO gigabytes big. Strip them out and you are left with the 40 to 100 MB of files a program actually needs to run. That answers the size question from the start, and it also explains why you can start hundreds of containers: you are not booting hundreds of operating systems, only starting programs that each bring their own small set of files.

The key insight: one shared kernel

If the image has no kernel, who runs the cp inside it? The host's kernel.

Your host has its own /bin, /lib and /usr. Container A has its own copies. Container B has its own copies. Each of them is a separate set of files. But when any program, on the host or in any container, wants to open a file, send a packet or start a process, it makes a system call, and every system call lands in the same single Linux kernel. That kernel then drives the real CPU, RAM, disk and network card.

So the container ends at the kernel line. Above it, everything is separate: the host cannot run the container's binaries and the container cannot run the host's. Below it, everything is shared.

Separate files above the line, one shared Linux kernel below it. Every system call from the host and from every container lands in the same kernel.
from video content

The version from the video, with the note that leads into the next section: it works on my laptop, but not on the prod server.

Why that is so useful

Every developer has said it: "it works on my machine". It works locally because your laptop happens to have the right Node version, the right libssl, the right config. Production has something slightly different and the app breaks.

With a container you ship the app together with the exact runtime and libraries it needs. The production server only has to provide one thing: a Linux kernel. The container's files never touch the server's files, and the server's files never touch the container's. Same image, same behaviour, everywhere.

The app ships with its own runtime and libraries. The server only provides a Linux kernel, so the same image behaves the same everywhere.

That answers question 1. An image is a slim root filesystem made for one job. Now question 2: if I hand you that folder as a zip, how do you run it so it behaves like its own machine? Just unzipping it and running bin/bash would not isolate anything.

Question 2, part 1: who starts the container

Two pieces of software do the work.

The container daemon (on a Docker install that is dockerd plus containerd) does the logistics. It pulls the image from a registry such as Docker Hub or Amazon ECR, unpacks the layers, writes an OCI runtime spec (a config.json that follows the Open Container Initiative standard) and prepares the root filesystem.

Then it hands everything to runc. runc is a small command-line tool, written in Go, maintained by the Open Container Initiative. It is the piece that actually creates the container. It does two critical things: it creates namespaces and it sets up cgroups. Both are plain Linux kernel features.

The daemon does the logistics (pull, unpack, write the OCI spec, prepare the root filesystem). runc does the actual work: namespaces and cgroups.
from video content

Where it starts: containerd on the host pulls the image from a registry such as ECR or Docker Hub, and the container is run from it.

web page

runc on GitHub: the CLI tool for spawning and running containers according to the OCI specification.

github.com/opencontainers/runc

Question 2, part 2: namespaces

A namespace gives a process its own private view of one part of the system. Start with the easiest one, the PID namespace.

On your Linux host every process has an ID. systemd is 1, sshd is maybe 812, your Python script is 4632. Create a new PID namespace and start a process in it, and inside, that process sees itself as PID 1. Its children are 2, 3, 4. It cannot see or signal any host process. From the host you still see it as 4632.

runc does the same for every other part of the system:

  • NET: its own network interfaces, routing table and ports.
  • MNT (mount): its own list of mounted filesystems, so its / can be the image's files.
  • UTS: its own hostname and domain name.
  • IPC: its own shared memory and message queues.
  • USER: its own mapping of user and group IDs.
  • CGROUP: its own view of the cgroup tree.
  • TIME: its own boot and monotonic clocks (newest one, Linux 5.6+).

Put them together and you get one logical space inside the same Linux machine where the image runs, with its own processes, network, mounts, hostname, IPC and users. That space is what we call a container.

One process, many private views: PID, network, mount, UTS, IPC, user, cgroup and time namespaces together make the space we call a container.

Quick detour on mounts, because people get stuck here. If you plug in a pen drive, it shows up as a device such as /dev/sdb1. Mount it on an empty folder /abc and ls /abc now lists the pen drive's files. A mount namespace gives the container its own private list of those attachments.

Mounting attaches a device such as /dev/sdb1 to a folder such as /abc. A mount namespace gives the container its own private list of these attachments.
web page

The namespace types, from the Linux man page namespaces(7).

namespaces(7) on man7.org

Question 2, part 3: cgroups

Namespaces control what a process can see. They do nothing about how much it can use. A container in its own namespaces could still eat all 8 cores and all 16 GB.

cgroups (control groups) fix that. You put the process in a group and write limits into files: one CPU, 2 GB of memory. The kernel enforces it. Go past the memory limit and the kernel's OOM killer stops the process. That is what docker run --cpus=1 --memory=2g sets under the hood.

Namespaces decide what a process can see; cgroups decide how much it can use. Here the group is limited to one CPU and 2 GB of memory.

The whole idea in one line

Image plus namespaces plus cgroups equals a container. The image is just files, namespaces are a Linux feature, cgroups are a Linux feature. No magic, just a normal Linux process with a private view and a fence around its resources.

Image + namespaces + cgroups = container. Files, plus two Linux kernel features.

Replaying docker run -it ubuntu

Now we can replay the command from the start:

  1. The docker CLI sends the request to the daemon.
  2. The daemon pulls ubuntu from the registry and unpacks the layers.
  3. It writes the OCI runtime spec and prepares the root filesystem.
  4. runc creates the namespaces.
  5. runc puts the process into a cgroup with its limits.
  6. runc jails the process inside the image's files, so / is now the image.
  7. runc starts the command from the image's config (CMD / ENTRYPOINT, here /bin/bash). It becomes PID 1 inside the container, and from here the container talks straight to the host kernel.

That is both questions answered.

docker run -it ubuntu, step by step: CLI, daemon, pull and unpack, OCI spec, namespaces, cgroup, jail, then /bin/bash as PID 1.
from video content

The same flow as I drew it in the video: registry to containerd, OCI spec and root filesystem to runc, then namespaces, cgroups, the jail and exec.

"But I ran this on a Mac"

Fair point. macOS and Windows kernels do not have Linux namespaces or cgroups. Docker Desktop quietly runs a small Linux virtual machine, and your containers share that VM's Linux kernel. The CLI on your Mac just talks to it. Everything in this post happens inside that VM.

On a Mac, Docker Desktop runs a small Linux VM. The containers share that VM's kernel, and the CLI on macOS just talks to it.

Going deeper: runc in the source

For readers who want to see it in the source. All snippets are from opencontainers/runc at commit 9d3029f (main, 8 Nov 2026).

The namespace types runc knows about. Eight, matching the kernel.

namespaces_linux.go libcontainer/configs/namespaces_linux.go:10-19 @ 9d3029f
const (
	NEWNET    NamespaceType = "NEWNET"
	NEWPID    NamespaceType = "NEWPID"
	NEWNS     NamespaceType = "NEWNS"
	NEWUTS    NamespaceType = "NEWUTS"
	NEWIPC    NamespaceType = "NEWIPC"
	NEWUSER   NamespaceType = "NEWUSER"
	NEWCGROUP NamespaceType = "NEWCGROUP"
	NEWTIME   NamespaceType = "NEWTIME"
)

Creating a container object. Before anything runs, runc validates the ID and the config, makes sure the state directory does not exist yet, and builds a cgroup manager. Right after this excerpt it refuses to reuse a cgroup that still has processes in it.

factory_linux.go libcontainer/factory_linux.go:35-61 (excerpt) @ 9d3029f
func Create(root, id string, config *configs.Config) (*Container, error) {
	if root == "" {
		return nil, errors.New("root not set")
	}
	if err := validateID(id); err != nil {
		return nil, err
	}
	if err := validate.Validate(config); err != nil {
		return nil, err
	}
	if err := os.MkdirAll(root, 0o700); err != nil {
		return nil, err
	}
	stateDir, err := securejoin.SecureJoin(root, id)
	if err != nil {
		return nil, err
	}
	if _, err := os.Stat(stateDir); err == nil {
		return nil, ErrExist
	} else if !errors.Is(err, os.ErrNotExist) {
		return nil, err
	}

	cm, err := manager.New(config.Cgroups)
	if err != nil {
		return nil, err
	}

How the jail is chosen. The video says runc "jails the process with chroot". In practice runc uses the stronger pivot_root whenever a mount namespace exists, and only falls back to chroot when there is none. chroot only changes where / points for path lookups. pivot_root actually swaps the root mount, so the old root can be unmounted and there is nothing to escape back to.

rootfs_linux.go libcontainer/rootfs_linux.go:238-244 @ 9d3029f
	if config.NoPivotRoot {
		err = msMoveRoot(config.Rootfs)
	} else if config.Namespaces.Contains(configs.NEWNS) {
		err = pivotRoot(rootFd)
	} else {
		err = chroot()
	}
Show pivotRoot and chroot
rootfs_linux.go libcontainer/rootfs_linux.go (excerpt) @ 9d3029f
func pivotRoot(root *os.File) error {
	// While the documentation may claim otherwise, pivot_root(".", ".") is
	// actually valid. What this results in is / being the new root but
	// /proc/self/cwd being the old root. Since we can play around with the cwd
	// with pivot_root this allows us to pivot without creating directories in
	// the rootfs. Shout-outs to the LXC developers for giving us this idea.

	oldroot, err := linux.Open("/", unix.O_DIRECTORY|unix.O_RDONLY|unix.O_PATH|unix.O_CLOEXEC, 0)
	if err != nil {
		return err
	}
	defer unix.Close(oldroot)

	// Change to the new root so that the pivot_root actually acts on it.
	if err := unix.Fchdir(int(root.Fd())); err != nil {
		return &os.PathError{Op: "chdir", Path: root.Name(), Err: err}
	}

	if err := unix.PivotRoot(".", "."); err != nil {
		return &os.PathError{Op: "pivot_root", Path: ".", Err: err}
	}

	// Currently our "." is oldroot (according to the current kernel code).
	// However, purely for safety, we will fchdir(oldroot) since there isn't
	// really any guarantee from the kernel what /proc/self/cwd will be after a
	// pivot_root(2).

	if err := unix.Fchdir(oldroot); err != nil {
		return &os.PathError{Op: "fchdir", Path: "fd " + strconv.Itoa(oldroot), Err: err}
	}

	// Make oldroot rslave to make sure our unmounts don't propagate to the
	// host (and thus bork the machine). We don't use rprivate because this is
	// known to cause issues due to races where we still have a reference to a
	// mount while a process in the host namespace are trying to operate on
	// something they think has no mounts (devicemapper in particular).
	if err := mount("", ".", "", unix.MS_SLAVE|unix.MS_REC, ""); err != nil {
		return err
	}
	// Perform the unmount. MNT_DETACH allows us to unmount /proc/self/cwd.

func chroot() error {
	if err := unix.Chroot("."); err != nil {
		return &os.PathError{Op: "chroot", Path: ".", Err: err}
	}
	if err := unix.Chdir("/"); err != nil {
		return &os.PathError{Op: "chdir", Path: "/", Err: err}
	}
	return nil
}

runc is just a CLI. Its main.go is a list of flags (--debug, --log, --root, --cgroup-manager, --rootless and more). The daemon calls it like any other program.

main.go main.go:105-140 (global CLI flags, excerpt) @ 9d3029f
	app.Flags = []cli.Flag{
		&cli.BoolFlag{
			Name:  "debug",
			Usage: "enable debug logging",
		},
		&cli.StringFlag{
			Name:  "log",
			Value: "",
			Usage: "set the log file to write runc logs to (default is '/dev/stderr')",
		},
		&cli.StringFlag{
			Name:  "log-format",
			Value: "text",
			Usage: "set the log format ('text' (default), or 'json')",
		},
Show the rest of the flags
main.go main.go:105-140 (continued) @ 9d3029f
		&cli.StringFlag{
			Name:  "root",
			Value: root,
			Usage: "root directory for storage of container state (this should be located in tmpfs)",
		},
		&cli.StringFlag{
			Name:  "cgroup-manager",
			Value: "cgroupfs",
			Usage: "cgroup manager to use ('cgroupfs' or 'systemd'); the latter expects cgroupsPath to be of form \"slice:prefix:name\" for e.g. \"system.slice:runc:434234\"",
		},
		&cli.BoolFlag{
			Name:  "systemd-cgroup",
			Usage: "same as --cgroup-manager=systemd (deprecated)",
		},
		&cli.StringFlag{
			Name:  "rootless",
			Value: "auto",
			Usage: "ignore cgroup permission errors ('true', 'false', or 'auto')",
		},
	}

Next: build one by hand

In Part 2 we throw Docker away and build a container by hand with debootstrap, unshare, a veth pair and a cgroup, then curl a Node server running inside it.

More internals, with interactive diagrams, on cloudmash.dev.