Start here. By the end of this chapter you will know what the Docker client is, what it is not, and where it came from.

The Docker client is the command-line program named docker. When you type a command that begins with the word “docker,” you are using the Docker client. It is the main way that people give instructions to Docker: start a container, list running containers, build an image, stop something, look at logs, and so on.

To follow the rest of this article, you only need two simple ideas. A container is a small, isolated box in which a program runs, together with everything the program needs, so that it behaves the same on every computer. An image is the recipe or blueprint from which containers are made. If you have never used either, do not worry: each of them is explained again, with pictures, in Chapter 3.

The client is not the engine

The most important sentence in this article is this one: the Docker client is not the thing that runs containers. Containers are created and managed by a separate background program called the Docker daemon, whose program name is dockerd. The word “daemon” is an old computing term for a program that runs quietly in the background, waiting for work. The client and the daemon are two different programs. They can run on the same computer, or on two computers far apart. They talk to each other using a defined set of messages called the Docker Engine API.

A short history

Docker was introduced to the public in 2013, and from the beginning it was built as a client and server system: a small command-line tool talking to a background service. That design was a deliberate choice, and it has proven very durable. Over the years, the client and the engine were separated more clearly. The client’s code lives in its own project, it can be installed on its own, and today it is often packaged separately from the daemon. Around 2017 the open-source project behind the engine was renamed Moby, while the products kept the Docker name. Later, the client gained a plugin system, which is how tools such as the modern image builder and the Compose tool for multi-container applications became part of the same “docker” command. Desktop products for Mac and Windows arrived that hide the daemon inside a lightweight virtual machine, while the client stays on your own computer. The client you use today is a mature, well-tested messenger with a long list of abilities.

Where you meet it

You meet the Docker client on developers’ laptops, on servers, in build machines that produce software, in classrooms, and inside countless scripts and automation systems. Whenever a person or a program types “docker” followed by a word, the client is at work.

If the daemon does the real work, why does a client exist at all? To see the answer, imagine life without it.

Running containers is complicated underneath

Behind every container are several deep features of the operating system. Some of them keep containers isolated from each other, so that one cannot see the files or processes of another. Some limit how much memory and processor time a container may use. Others build private networks and virtual file systems. Setting all of that up by hand, for every container, would take a great deal of specialist knowledge and a lot of careful typing. The daemon hides all of that behind simple ideas such as “start this container.”

Talking to the daemon directly is awkward

The daemon listens for requests written in the format of the Docker Engine API, which uses the same style as web requests. You could, in principle, send those requests yourself by hand, but each one would be long, full of details, and easy to get wrong. The client turns a short, friendly phrase such as “docker ps” into the correct request, sends it, waits for the reply, and shows the result in a form that a person can read. It is a translator between human language and machine language.

Separation gives freedom

Because the client and the daemon are separate, several useful things become possible. The daemon can run on a powerful server while you type on a light laptop. One person can control many machines by pointing the client at each in turn. Other programs, such as build systems, dashboards and scripts, can talk to the same daemon without going through a human-friendly command line at all. And the client can be improved, with new commands and plugins, without changing the daemon.

In short, the client gives Docker a friendly face. The rest of this article shows how that face works and how to use it well.

A dozen words unlock the whole subject. Each one is explained with what it is, why it exists, where you meet it, and a picture from everyday life.

Container

A container is an isolated box in which one program runs, together with the files and tools that it needs. From inside, the program feels as if it has a whole computer to itself. From outside, it is just another process on the machine. Containers start in seconds and can be created and thrown away freely. Think of a lunchbox: everything the meal needs is packed inside, and it can be carried anywhere.

Image

An image is a saved, read-only package from which containers are made. It holds the program, its libraries and its settings. You can create many containers from one image, just as you can bake many cakes from one recipe. Images are made of layers stacked on top of one another, which lets Docker share common parts and save space.

Registry

A registry is a place that stores and shares images, like a library of recipes. The best-known public registry is Docker Hub, and many companies run private registries of their own. When you ask for an image that your machine does not have, it is downloaded, or “pulled,” from a registry.

The daemon

The daemon, called dockerd, is the background program that owns your containers, images, networks and storage. It receives requests, carries them out, and reports back. It is the kitchen of the restaurant.

The Docker Engine API

The Docker Engine API is the agreed set of messages that clients use to talk to the daemon. It is versioned, which means that it changes in careful steps and clients and daemons can agree on which version to use. The Docker client is only one of many programs that speak this language. Others include software libraries for programming languages, graphical tools and automation systems. The API is the shared menu that every waiter and every kitchen understand.

The socket

A socket is a special doorway through which two programs on the same computer can talk. On Linux and Mac systems, the daemon by default listens on a socket file, and the client sends its requests through that file. On Windows the same idea uses a named pipe. A socket is like an internal telephone line between two rooms of a building.

The context

A context is a saved description of which daemon the client should talk to, together with any needed security details. You can keep several contexts, such as “laptop,” “staging” and “production,” and switch between them. A context is a speed-dial button on your remote control.

The configuration file

The client keeps its settings in a small file inside your home folder, in a directory named .docker. It records things such as saved logins to registries, the currently chosen context and preferences. Like the settings menu of any program, it saves you from repeating yourself.

Plugins

A plugin is an extra program that adds new commands to the client. The modern image builder, the Compose tool for running groups of containers, and a tool for examining images for known weaknesses are examples. They appear as ordinary subcommands, so from your point of view they simply extend the vocabulary of the remote control.

Command, subcommand and flag

A Docker command has a simple shape. It starts with “docker,” followed by a subcommand that names what you want, such as “run” or “ps,” and often by flags, which are small options that start with a dash and adjust the behavior. Newer commands are grouped by subject: for example, “docker container ls” lists containers, and “docker image ls” lists images. Learning this shape lets you guess many commands you have never seen.

Now let us zoom out and look at the whole machine: which parts exist, where each one lives, and how the client fits among them.

Docker is not one program but a small team of programs. The client is the one on the surface. Behind it are several others, each with a clear job. The diagram below shows the whole chain, from your keyboard down to a running container.

flowchart LR
    USER["You in a terminal"] --> CLI["Docker client - the docker program"]
    CLI -->|"Engine API requests"| SOCK["Local socket or network address"]
    SOCK --> D["Docker daemon - dockerd"]
    D --> CT["containerd - manages container lifecycle"]
    CT --> RC["runc - starts the container process"]
    RC --> C["Running container"]
    D |"pull and push images"| REG["Registry such as Docker Hub"]
    D --> ST["Images, volumes and networks on disk"]

Walking through the diagram

On the far left is you, typing in a terminal. The Docker client reads your command and turns it into a request in the language of the Engine API. It sends the request to an endpoint: either a local socket file, when the daemon is on the same computer, or a network address, when it is on another one. The daemon receives the request. It keeps records of all the images, containers, networks and storage volumes, and it decides what needs to happen. To actually start and supervise a container, the daemon relies on a helper called containerd, which manages the life of containers, and containerd relies on a smaller helper called runc, which does the final step of creating the isolated process. The daemon also talks to registries when images have to be downloaded or uploaded.

Where each part lives

One machine or two?

On a Linux computer with Docker installed, the client and the daemon live side by side, and the client speaks to the daemon through a local socket file. On a Mac or a Windows computer, the situation is different, because the containers that Docker runs are built on features of Linux. Desktop products therefore run a small, hidden Linux virtual machine, and the daemon lives inside it. The client stays on your Mac or Windows system and reaches the daemon through a doorway the product provides. From the outside, it looks as if everything is on one machine, but underneath there are still two programs and a bridge between them. That is why a folder on your laptop is not automatically visible inside a container: the daemon runs in another place, and sharing has to be set up.

The client on its own

Because the client is separate, it can be installed without the daemon. Many operating systems offer a package that contains only the client. This is what you want on a machine that will only steer remote daemons, such as a build agent or an administrator’s workstation. The client alone cannot run a single container, but it can command any daemon it is allowed to reach.

This is the engine room. You do not need to be an expert, because every step comes with a picture.

sequenceDiagram
    participant U as You
    participant C as Docker client
    participant D as Docker daemon
    participant R as Registry
    U->>C: docker run hello-world
    C->>C: Read settings and choose the target daemon
    C->>D: Ask which API version you support
    D-->>C: Supported version
    C->>D: Create a container from the image
    D->>R: Pull the image if it is missing
    R-->>D: Image layers
    D-->>C: Container created
    C->>D: Start the container and attach to its output
    D-->>C: Stream the output
    C-->>U: Print the output and exit with the container's exit code

Step one: read the settings

Before doing anything, the client works out where to send its request. It looks at the command line, at a few environment variables, and at the configuration file to decide which daemon is the target. If you have chosen a context, that context supplies the address. If not, the client falls back to the default local socket. It also reads which registry logins you have saved.

Step two: agree on a language version

The client and the daemon may have been released at different times, so they may know different versions of the Engine API. The client therefore starts with a tiny greeting, asking the daemon which version it supports, and then speaks the newest version that both understand. This is called version negotiation. It is like two travelers who discover that they speak slightly different dialects and agree to use the one they both know. If the daemon is far too old or far too new, the client explains the mismatch, and you can also pin a version by hand.

Step three: turn the command into requests

The command “docker run” is really a short way of saying several things: make sure the image exists, create a container from it with the options you gave, start it, and connect to its output. The client sends these as separate requests. First it asks the daemon to create the container, passing along every option: the name, the ports, the folders to share, the settings for memory and so on. The daemon answers with the identifier of the new container.

Step four: the daemon does the work

If the image is not yet on the machine, the daemon downloads it from the registry, layer by layer, and the client shows a progress display of what the daemon reports. Notice who does what: the daemon talks to the registry, not the client. The client’s part is to carry your saved login details along with the request so that the daemon can identify itself to a private registry. Once the container exists, the client asks the daemon to start it. The daemon hands the job to containerd and runc, which create the isolated process.

Step five: streaming the output

To show you what the program prints, the client keeps the connection open and receives a continuous stream of output. For interactive commands, where you type into a running program, the connection is turned into a two-way channel, so that your keystrokes travel to the container and its answers travel back, just like a telephone call that stays open while both people talk. Two flags control this: one keeps the input open and another gives the program a terminal to talk to, and together they are what make an interactive shell inside a container feel like a normal one.

Step six: finish and report

When the program inside the container ends, the daemon tells the client. The client then prints anything left over and ends with the same exit code that the container’s program produced. An exit code is a small number that says how things went: zero means success, and other numbers mean various failures. Scripts rely on this. The client also uses special codes for its own problems: one for an error from the daemon itself, one for a command that could not be run, and one for a command that was not found.

Some commands never leave your computer

Not every docker command needs a daemon. Asking for help, showing the client’s own version, listing or switching contexts, and logging in or out only touch local files. They work even when no daemon is reachable. This explains a common beginner puzzle: the command to show versions prints the client’s information but then complains about the server. The client is fine; it just could not reach a daemon.

The build context

Building an image is a special case. The instructions for a build are kept in a file, and they may refer to other files, such as your program’s source code. The client gathers those files into a package called the build context and sends it to the builder. A separate ignore file lets you leave out things that do not belong, such as large folders of temporary files. Sending a huge context is one of the most common reasons for slow builds, and Chapter 14 returns to it.

Containers are born, live, rest and die, and each step is triggered by a client command. Knowing this lifecycle makes every command easier to understand.

stateDiagram-v2
    [*] --> Created : docker create
    Created --> Running : docker start
    Running --> Paused : docker pause
    Paused --> Running : docker unpause
    Running --> Exited : program ends or docker stop
    Exited --> Running : docker start
    Exited --> Removed : docker rm
    Created --> Removed : docker rm
    Removed --> [*]

The states, one by one

A container begins as created: it exists as a set of settings and a file system, but no program is running yet. When you start it, it becomes running. A running container can be paused, which freezes its processes without ending them, and later unpaused. When its program ends, or when you stop it, the container becomes exited. It still exists, with its files and logs intact, and can be started again. Only when you remove it does it truly disappear. Many people are surprised that stopped containers stay on the disk until they are removed, which is why old ones pile up and need cleaning.

The shortcut: run

The command you will use most, “docker run,” is a combination: it creates a container and starts it, downloading the image first if needed. If you add the option to run in the background, the client returns your prompt immediately and the container keeps working. If you add the option that removes the container when it ends, no leftover exited container remains.

Three flows of data

Data travels between the client, the daemon and the registry in three main ways. First, commands and answers: small requests go to the daemon, and status information and output come back. Second, the build context: when you build, the client uploads the files needed for the build. Third, credentials: when the daemon must pull from or push to a private registry, the client supplies the login details, drawn from your saved settings, and the daemon uses them to speak to the registry. Images themselves flow between the daemon and the registry directly. They do not pass through the client.

Before going deeper, here is a short, safe walk through the client’s most common commands. Follow it once, and the rest of the article will feel familiar.

Before you begin

You need Docker installed on your computer. On Mac and Windows, the usual choice is a desktop application that includes both the client and a hidden daemon. On Linux, you can install the engine packages, and, if you wish, a separate client package. After installation, open a terminal. Every command below is typed there.

Reading the common error

The message beginners meet most often says that the client cannot connect to the daemon. It appears when the daemon is not running, when the client is pointed at the wrong address, or when you do not have permission to use the socket. The three fixes match the three causes: start the daemon, check which context or address the client uses, and, on Linux, make sure your user is allowed to use Docker, keeping in mind the security warning in Chapter 12.

One of the client’s best tricks is that it can steer any daemon it can reach. This chapter shows how it finds the daemon, and the different ways it can connect.

flowchart TD
    S["A docker command starts"] --> A{"Host or context option on the command line?"}
    A -->|"Yes"| H1["Use that target"]
    A -->|"No"| B{"Environment variable for host or context set?"}
    B -->|"Yes"| H2["Use the target from the variable"]
    B -->|"No"| C{"A current context saved in the settings?"}
    C -->|"Yes"| H3["Use the address stored in that context"]
    C -->|"No"| H4["Use the default local socket"]

How the client chooses

The client follows a simple order of priority. Something you type on the command line beats an environment variable, and an environment variable beats what is saved in the settings. If nothing at all is specified, the client uses the default local socket. The exact details can differ a little between versions, so when in doubt, ask the client which target it is using, as Chapter 13 explains.

Five ways to connect

Why the local socket is powerful

The local doorway is not protected by a password. It is protected by file permissions: only the administrator and members of a special group can use it. Anything that can talk to it can ask the daemon to start containers that reach into the machine’s files. For that reason, access to the Docker socket is treated as the same as administrator access. Chapter 12 returns to this point, because it is the most important safety fact about the client.

Contexts: speed dial for daemons

Typing long addresses every time would be tiring and risky. A context stores a name, an address and the security details, so that you can switch with a short command. You can create a context, list your contexts, see which one is active, switch to another, and remove one you no longer need. Desktop products usually add their own context automatically. With contexts, moving from your laptop’s daemon to a staging server and back is a one-word change, and every command you type afterward goes to the new target.

Using a context for one command

You can also choose a context for a single command without switching, by naming it in that command. This is safer for important actions, because your normal setting stays on the harmless local daemon, and only the one command you consciously aimed goes elsewhere.

The client has many commands, but they follow a pattern. Once you see the pattern, the whole map fits on one page.

The shape of a command

Modern Docker commands are grouped by subject, like drawers in a cabinet. The first word after “docker” names the drawer, such as container, image, network or volume. The second word is the action, such as ls to list, rm to remove, or inspect to see details. So “docker container ls” lists containers and “docker image rm” removes an image. Older short forms, such as “docker ps” for listing containers and “docker images” for listing images, still work and are very popular, because they are quicker to type.

Flags: small options with big effects

Flags adjust a command. For running containers, the most common ones are: run in the background, give the container a name, connect a port of your computer to a port of the container, share a folder, set an environment variable, limit memory, and remove the container when it ends. You do not need to memorize them. The help option, added to any command, prints a clear summary of everything it accepts.

Filtering and formatting

When you have hundreds of containers, a plain list is unwieldy. Many commands accept a filter option, which narrows the list to items that match, for example only containers that have exited. They also accept a format option, which lets you choose exactly which columns to print, or print the raw data in a structured form that other programs can read. This is what makes the client so useful in scripts: you can ask for precisely the piece of information you need, with no extra text to strip away.

Inspecting things

The inspect action prints a complete technical description of any object, from a container to a network, as structured data. It is your microscope: settings, addresses, mounted folders, health status and much more are all visible there. Combined with the format option, you can extract one value, such as a container’s internal address.

The client remembers things about you: which registries you use, which target you chose, and how you like your output. Knowing where this is kept explains many puzzling behaviors, and matters for security.

The configuration file

The client’s settings live in a small file, in a folder called .docker inside your home directory. It records saved registry logins or pointers to a secure store for them, the currently selected context, preferences about output, settings for a network proxy that containers should use, and the list of extra plugin folders. You can choose a different folder for this file with an environment variable, which is very useful in build systems where several jobs must not share logins.

Logging in to a registry

To pull private images or push your own, you log in to a registry with the “docker login” command. The client asks for your user name and a secret, sends them to the registry to check, and saves the result. Where it saves the result matters greatly. If you have set up a credential helper, a small program that stores secrets in the safe storage of your operating system, such as a system keychain, the client hands the secret to it. If you have not, the client writes the credentials into the configuration file, encoded but not encrypted. Encoding is like writing a message in a different alphabet that anyone can read back; it offers no protection.

Using login safely

Never type a secret directly into the command line, since it will be saved in your shell history and may be visible to other users on the machine. Instead, use the option that reads the secret from standard input, such as from a file or a secret manager, and use tokens with limited rights rather than your main password.

Environment variables

Plugins

Plugins are separate programs that the client finds in special folders and presents as ordinary subcommands. That is how the image builder and the Compose tool become part of the “docker” command. The information command lists the plugins the client has found and their versions. Plugins let Docker add features without making the core client larger, and they allow third parties to add commands of their own. Because a plugin is a program that runs with your rights, you should install plugins only from sources you trust.

The Docker client is a well-loved tool, but it is not the only way to talk to a daemon, and it has limits. Knowing them helps you choose wisely.

Trade-off one: convenience versus safety

The client makes powerful actions easy. That is its great strength and its main danger. A single command can remove every stopped container, or every unused image. The remedy is not to avoid the client but to build habits: read a command before you press Enter, check the active context, and use options that ask for confirmation.

Trade-off two: typing versus describing

Typing commands is quick for exploration, but a system built from typed commands is hard to repeat exactly. As soon as something matters, it should be described in a file, such as a Compose file or a script, and kept in version control. The client is then the tool that carries out the description, and no longer the place where the knowledge lives.

Trade-off three: the client versus other clients

Other programs also speak the Docker Engine API, and other tools offer a similar command line for other engines. Which one suits you depends on what you need.

Most teams end up using the client for exploration and operations, files and libraries for repeatable automation, and dashboards for shared visibility.

The Docker client is powerful, and power needs care. This chapter explains the key safety facts, none of which require special skills to follow.

The central fact: access to the daemon is administrator access

The daemon usually runs with the highest rights on the machine. Anyone who can send it requests can ask it to create containers that reach into the machine’s files and settings. For this reason, permission to use the Docker socket is, in practice, the same as administrator permission. On Linux, adding a user to the group that may use the socket is therefore a serious decision, not a convenience. The diagram below shows the logic in simple steps.

flowchart LR
    A["Anyone who can reach the Docker socket or an open network port"] --> B["Asks the daemon to start a container"]
    B --> C["The container is given access to folders of the host machine"]
    C --> D["Files on the host can be read or changed"]
    D --> E["Effective control of the whole machine"]

Rules that follow from it

Other everyday risks

Secrets placed in environment variables, or in command options, can be seen later by anyone who can inspect the container or read the shell history. Very high-privilege options, such as the one that removes most isolation from a container, should be avoided unless truly needed. Plugins and downloaded client programs run with your rights, so obtain them only from official sources and verify them. Finally, keep the client and the engine up to date, since security fixes are released regularly.

The client is your window into the daemon. Here are the commands that show what is happening, and the signs to watch for.

Which target, which versions?

Two quick checks answer most “why is this strange?” questions. The version command shows the client and the daemon side by side, so you can spot a mismatch or a missing daemon. The context command shows which target is active, so you can spot a wrong destination. Make these your first steps whenever behavior surprises you.

Seeing what containers are doing

The list command shows status at a glance, including health when a container defines a health check, a small test that Docker runs regularly to ask “is the program still working?” The logs command shows what a container has printed. The stats command shows live use of processor, memory and network for each running container, in the style of a task manager. The events command shows a live feed of what the daemon is doing: containers starting, stopping, dying or being created. Together these four give you a complete picture of everyday health.

Seeing what Docker is using

Docker quietly collects data: images, stopped containers, volumes and build leftovers. The system disk-usage command shows how much space each kind takes. Watching it prevents the classic surprise of a full disk. The information command reports counts of containers and images and the location where Docker keeps its data.

Debugging the client

The client has a debug option that makes it print more detail about what it is doing, and a log-level option for finer control. These help when the client and daemon fail to agree on something. The daemon’s own messages live in the system’s log, not in the client, so when the client says “the daemon returned an error,” look there for the reason.

The client itself is light, but the way you use it can make Docker feel fast or slow. Here are the habits that matter.

The client is thin

Almost all the work happens in the daemon and on the network, not in the client. A command such as listing containers costs the client almost nothing, and any slowness usually comes from the daemon, the disk or the network between the two.

Keep the build context small

The biggest avoidable slowness comes from the build context. If you build in a folder that also holds large data files, downloaded packages or old outputs, the client packs and uploads all of it, every time. Use the ignore file to leave out everything that the build does not need. When the daemon is on another machine, the upload crosses the network, and a small context saves a great deal of time.

Mind the distance

A client steering a remote daemon feels every millisecond of delay. Commands that stream a lot of output, or that make many small requests in a script, become slower. For heavy work, consider running the script closer to the daemon, or use a remote builder for images.

Scale with filters and formats

A machine with thousands of containers produces long lists. Ask for only what you need, with filters and formats, so that less data has to be fetched, shown and processed.

Build systems and registries

Build machines pull the same images again and again. Reusing cached layers, keeping a nearby mirror of popular images, and logging in to registries all reduce delays. Public registries also apply limits to how many anonymous downloads one address may make, so unauthenticated build machines can hit a wall at busy times.

Reliability in scripts

Write scripts so that they can be run twice without harm. Give containers fixed names and remove leftovers first, use options that remove containers when they end, check exit codes, and set sensible timeouts. Use health checks so that a script can wait until a program is really ready, rather than sleeping for a guessed number of seconds.

Patterns are recipes that experienced teams keep repeating because they work. Anti-patterns are the traps those same teams learned to avoid.

Patterns worth copying

Traps to avoid

A short, practical checklist drawn from careful teams, followed by the mistakes that trip up nearly everyone once.

Common mistakes and their cures

Here is how the Docker client is used in different settings. Named companies below are used as familiar illustrations of the kind of scale and problem involved, not as claims about their internal systems.

A complete walk-through: from laptop to server

To make everything concrete, here is a typical journey of a small application, and how the client is used at each step.

Through all eight steps, the client never changed. Only the target changed, and the client’s simple job of carrying your words to a daemon stayed the same.

Short answers to the questions that beginners ask most often.

The whole article in one place. If you remember only this box, you still know the essentials.