To understand the recipe card, first imagine life without one.

Before tools like Docker became popular, setting up an application on a new computer was a long, fragile ritual. A person would install the operating system, then install a programming language, then install a dozen libraries, then copy over the application files, then change a few settings, and finally hope everything worked. These steps often lived only in someone’s memory or in a messy document that was out of date the moment it was written.

The result was a famous problem: “It works on my machine.” The application ran perfectly on the developer’s laptop but failed on the test server, because some small step had been done differently. Nobody could say exactly what the differences were, because the setup had never been written down in a precise, repeatable way.

A Dockerfile solves this by turning the whole setup ritual into a short, readable text file. Every step is written down in order. Docker reads the file and carries out each step automatically, the same way every time, on any machine. The recipe is no longer hidden in someone’s head. It lives in a file that can be read, shared, reviewed, and improved by the whole team.

A short glossary will make the rest of this guide easy to follow.

A Dockerfile is a text file of instructions, read from top to bottom, that describes how to assemble an image.

A Dockerfile is an ordinary text file. By convention, it is simply named Dockerfile, with a capital D and no file extension, and it usually sits in the main folder of a project. You can open it in any text editor. There is nothing mysterious inside: just lines of text, each starting with a keyword that says what to do, followed by the details.

The file describes the whole story of an image. It says which base to start from, which extra software to add, which of your own files to bring in, which settings to apply, and which command should run when a container starts. When you ask Docker to build, it reads these lines from the first to the last, carrying out each one in order, and the final result is an image.

Declarative and Simple

The Dockerfile describes what the image should contain, not how to click through a computer to get there. You do not open windows or type into a terminal by hand. You write down the recipe once, and Docker does the work. This is why people describe Dockerfiles as a form of “infrastructure written as text,” an idea that makes environments predictable and easy to review.

The Dockerfile is the first stop on the journey from your code to a running application.

The path from an idea to a working application has several stages, and the Dockerfile sits right at the start. A developer writes the recipe. Docker builds an image from it. The image is stored, often in a registry, so that it can be shared. Then any machine can pull the image and start containers from it. Each stage produces something different, and understanding the differences prevents a lot of confusion.

flowchart LR
  A["Your project files"] --> B["Dockerfile: the recipe"]
  B -->|build| C["Image: the packaged result"]
  C -->|push| D["Registry: shared library"]
  D -->|pull| E["Any machine"]
  C -->|run| F["Container: the running application"]
  E -->|run| G["Container: another copy"]
        

Notice the last stage. Once an image is built, the machines that run it do not need the Dockerfile at all. The image carries everything. The Dockerfile remains valuable as the source of truth, because if you ever need to rebuild or change the image, the recipe is exactly where you go.

A Dockerfile is built from a small vocabulary of instructions. Learn these and you can read almost any Dockerfile.

Each line of a Dockerfile starts with an instruction keyword, conventionally written in capital letters, followed by its arguments. There are only a handful of instructions that matter for everyday work. The following cards introduce the most important ones in plain words.

Instructions That Shape the Image

Instructions That Record Settings

Instructions That Decide What Runs

The order of the lines is not decoration. It is the order of the story.

Docker reads a Dockerfile from the first line to the last, and each instruction builds on the results of the one before it. The first instruction chooses the foundation. Later instructions add to it. If you place a step too early, something it needs may not exist yet. If you place a step too late, you may lose the benefits of caching. So the sequence of lines is one of the most important design decisions in the file.

There are a few small rules of the language. A line beginning with a hash symbol is a comment, meant for human readers, and Docker ignores it. A very long instruction can be split over several lines using a continuation mark at the end of each line, which keeps the file tidy. Blank lines are ignored. Beyond that, the format is deliberately simple, and that simplicity is why beginners pick it up so quickly.

A Dockerfile can only copy files that Docker has been handed. That handed-over folder is called the build context.

When you ask Docker to build an image, you point it to a folder, and that folder is packaged up and sent to the builder. This is called the build context. It is the only set of files that your copy instructions are allowed to reach. Your instructions cannot wander off and grab files from elsewhere on your computer. They can only see what is inside the context.

A common beginner mistake is to leave a huge folder in the context, such as downloaded data, test results, or a big history of version-control files. Docker dutifully sends all of it to the builder, which slows every build and can even leak files into the image that should never have been there.

The Ignore File

To solve this, Docker supports a companion file named .dockerignore, placed beside the Dockerfile. It lists the files and folders that must be left out of the build context. Think of it as a “do not pack” list. Anything named in it is never sent to the builder, so it cannot end up in the image and cannot slow down the build.

flowchart TD
  A["Project folder"] --> B{"Listed in the ignore file?"}
  B -- Yes --> C["Left out of the build context"]
  B -- No --> D["Sent to the builder as part of the context"]
  D --> E["Available to copy instructions in the Dockerfile"]
        

Watching the build from the inside shows why each instruction matters.

When you start a build, the Docker builder reads the Dockerfile and works through the instructions in order. For each instruction that changes files, the builder runs the step in a temporary environment, records exactly which files changed, and saves that record as a new layer. Instructions that only record settings, such as the start command, are stored in the image’s configuration. At the end, the builder seals everything together into a finished image and gives it a name.

Modern Docker uses a builder called BuildKit, which is smarter and faster than older ones. It can build independent steps at the same time, skip work whose results are already remembered, and handle sensitive values more safely. Most of the time you do not need to think about it, but it is the engine that makes builds feel quick.

sequenceDiagram
  participant You as You
  participant CLI as Docker CLI
  participant D as Docker builder
  participant Reg as Registry
  You->>CLI: Ask to build from the Dockerfile
  CLI->>D: Send Dockerfile and build context
  D->>Reg: Fetch the base image layers if missing
  Reg-->>D: Send base layers
  D->>D: Run each instruction and save layers
  D-->>CLI: Report the finished image
  CLI-->>You: Image is ready with its name and tag
        

A well-written Dockerfile builds in seconds because it makes good use of the cache.

Every file-changing instruction in a Dockerfile produces a layer, and Docker remembers these layers. The next time you build, Docker compares each instruction with its memory. If an instruction and everything before it are unchanged, Docker reuses the stored layer and skips the work. This is called a cache hit, and it is the reason a second build can be dramatically faster than the first.

There is one crucial rule. As soon as one instruction changes, that layer and every layer after it must be rebuilt, because each layer sits on top of the ones before. So the cache only helps as an unbroken chain from the top of the file down to the first change.

flowchart TD
  A["Instruction 1: choose base"] --> B{"Unchanged?"}
  B -- Yes --> C["Reuse cached layer"]
  B -- No --> X["Rebuild this and everything after"]
  C --> D["Instruction 2: install dependencies"]
  D --> E{"Unchanged?"}
  E -- Yes --> F["Reuse cached layer"]
  E -- No --> X
  F --> G["Instruction 3: copy your code"]
  G --> H{"Files changed?"}
  H -- Yes --> Y["Rebuild only this and later steps"]
  H -- No --> Z["Reuse cached layer"]
        

The Golden Rule of Ordering

Put the steps that rarely change at the top and the steps that change often at the bottom. Installing software and dependencies changes rarely, so it belongs near the top. Your own code changes many times a day, so it belongs near the bottom. That way, an everyday code edit only rebuilds the last few layers, and the slow steps come straight from the cache.

Beginners often mix up these three, because all of them involve running commands. The difference is when they run.

The key question is: “At what moment does this command happen?” One of them happens while the image is being built. The other two happen only later, when a container starts. Once you attach the correct moment to each, the confusion disappears.

Using CMD and ENTRYPOINT Together

The two can cooperate. The entrypoint names the fixed program, and the command supplies its default arguments. Anyone starting the container can then replace just the arguments without touching the program. For example, an image built to be a converter tool might always run the converter program, while the default arguments say which file to convert, and the user can supply a different file at start-up.

Only the last CMD in a Dockerfile takes effect. If you write several, the earlier ones are simply ignored. This surprises people who expect all of them to run.

Two more pairs of similar-looking instructions deserve a quick explanation.

COPY Versus ADD

Both bring files into the image. COPY does exactly one simple thing: it copies what you name from the build context. ADD does that too, but it has extra abilities, such as downloading from a web address and automatically unpacking some kinds of archives. Because those extras can cause surprises, the common advice is to prefer COPY for ordinary work and use ADD only when you truly need its special powers.

ARG Versus ENV

Both hold values, but they live for different lengths of time. ARG values exist only while the image is being built. They are useful for choosing a version or a build option, and they vanish afterwards. ENV values are stored in the image and remain visible to the container while it runs. Use ARG for build-time choices and ENV for settings the running application needs.

The first instruction you write affects almost everything that follows.

The base image is the foundation of your stack. It decides how big your image is, how many programs are pre-installed, how easy it is to work with, and how many security weaknesses you inherit. Choosing well at the start saves effort for the whole life of the image.

How to Decide

Prefer official images from sources you trust, because they are maintained and patched by experts. Prefer smaller bases when your application allows it, because fewer programs mean fewer possible weaknesses and faster downloads. And name a specific version rather than relying on a moving label like “latest,” so that your build gives the same answer next month as it does today.

A single Dockerfile can contain several stages, and only the last one becomes the final image.

Building an application often needs heavy tools, such as compilers and testing programs, that are useless once the application is finished. If you leave them in the final image, it becomes large and full of unnecessary software. A multi-stage build fixes this by splitting the Dockerfile into stages. An early stage has all the heavy tools and produces the finished application. A later stage starts from a small, clean base and copies in only the finished result. Everything else is discarded.

flowchart LR
  A["Stage 1: large image with compilers and tools"] --> B["Build and test the application"]
  B --> C["Finished application files"]
  C -->|copy only the result| D["Stage 2: small clean base"]
  D --> E["Final image: lean and secure"]
  A -.->|discarded| F["Heavy tools and temporary files"]
        

Many security decisions are made in the recipe, long before any container runs.

Because a Dockerfile decides what goes into an image and how the container will behave, it is the best place to make an application safer. A few careful choices here protect every container built from the image.

A Dockerfile is code, and like any code it benefits from checking.

Because a Dockerfile is a text file, tools can read it and point out mistakes before you ever build. Community tools known as linters scan a Dockerfile for common problems, such as unpinned versions, missing cleanup, or risky habits, and suggest improvements. Adding a linter to your automated checks is an easy way to keep quality high across a team.

During and after a build, several signals help you understand what you produced. The build output shows each step, how long it took, and whether it came from the cache. An image history view lists every layer and how many bytes it added, which is the fastest way to find a bloated step. A vulnerability scan reports known weaknesses in the packages inside the image.

Writing the recipe as a file brings real benefits, along with a few costs.

A table to keep the Dockerfile separate from other things it is often confused with.

Dockerfile Versus a Shell Script

A shell script performs steps on a computer that already exists, and the outcome depends on what state that computer was in. A Dockerfile builds from a clean, known starting point every time, and produces a sealed image as its output. That difference is what makes Dockerfile results so predictable.

Dockerfile Versus a Compose File

A Dockerfile describes how to build one image. A Compose file, which is a different file, describes how to run several containers together, such as a web application, a database, and a cache. They often work as a team: the Compose file points to Dockerfiles for the images it needs to build.

Dockerfiles appear wherever teams want reliable, repeatable software packaging.

Some habits make Dockerfiles a pleasure to maintain. Others create slow builds and heavy images.

Helpful Patterns

Anti-Patterns to Avoid

A short list to help you write Dockerfiles that are small, fast, and safe.

Build problems feel scary at first, but they usually fall into a few familiar groups.

When a build fails, Docker stops at the exact instruction that went wrong and shows the message from that step. That is the biggest clue you will get, so always read the error from the step where it stopped rather than from the very top. Asking the right questions in a sensible order usually leads to the cause quickly.

flowchart TD
  A["Build failed"] --> B{"Which instruction stopped?"}
  B --> C{"Is it a file-copy step?"}
  C -- Yes --> D["Check the build context and the ignore file for the missing file"]
  C -- No --> E{"Is it an install step?"}
  E -- Yes --> F["Check network access, package names, and version numbers"]
  E -- No --> G{"Is it the base image step?"}
  G -- Yes --> H["Check the image name, tag, and registry access"]
  G -- No --> I["Read the full error message and the earlier steps for clues"]
        

A Dockerfile is a plain text file of ordered instructions that tells Docker how to build an image, including which base to use, which software and files to add, and what to run at start-up.

No. The Dockerfile is the recipe, and the image is the finished result of following it. A container is then a running copy made from the image.

It is simply the default name Docker looks for. You may use a different name if you tell Docker which file to read, but the standard name keeps things simple and familiar.

No. Instructions that change files, such as running a command or copying files, create layers. Instructions that only record settings add information to the image’s configuration without adding meaningful file content.

RUN executes during the build and saves its results into the image. CMD sets the default command that runs later, when a container starts. Build-time work belongs in RUN, and start-up behavior belongs in CMD or ENTRYPOINT.

No. You can run containers from existing images, such as those from a public registry, without ever writing a Dockerfile. You write one when you want to build your own image.

Because a change to an early instruction invalidates the cache for every instruction after it. Reorder your file so stable steps come first and your own code is copied near the end.

You can write more than one, but only the last one takes effect. The earlier ones are ignored, which surprises many beginners.

Choose a small base image, install only what you need, clean up within the same step that creates temporary files, use an ignore file, and use multi-stage builds so heavy tools never reach the final image.

No. A Dockerfile describes how to build a single image. A Compose file describes how to run and connect several containers together. They are different files with different jobs, and they often work together.

A Dockerfile is the written recipe behind every custom Docker image. It is a simple text file of ordered instructions: a base to start from, steps that add software and files, settings that describe the environment, and a command that says what runs when a container starts. Docker reads the file from top to bottom, turns each file-changing step into a layer, and seals the result as an image that can be shared and run anywhere. Because the recipe is text, it can be versioned, reviewed, linted, and automated, which turns fragile setup rituals into repeatable engineering. Good Dockerfiles order their steps to use the cache, keep secrets out, run as an ordinary user, and use multi-stage builds to ship only what is needed. Once you see the Dockerfile as the first link in the chain from recipe to image to container, the rest of Docker falls into place.