What Is a FROM Instruction in Docker?
The very first line of almost every Dockerfile, explained from zero: what it does, why it exists, every part of its syntax, and the habits that separate a fragile build from a reliable one.
Every recipe begins somewhere. A cake recipe assumes you already have an oven, a bowl, and basic ingredients like flour and sugar. It never explains how to build an oven from raw metal, because that would be absurd. It simply says, in effect, “start with these basics already in place,” and then lists what to add.
A Dockerfile, the plain text recipe that tells Docker how to build an image, works exactly the same way. Its very first meaningful line almost always says, in effect, “start with this already-prepared foundation.” That line is called the FROM instruction, and it is arguably the single most important line in the entire file.
In this guide you will learn exactly what the FROM instruction does, why it must come first, every part of its structure, how it connects to multi-stage builds, and the habits that keep it safe and predictable. Every new term is explained the moment it appears, paired with an everyday comparison to make it stick.
By the end, you should be able to look at any Dockerfile’s opening line and immediately understand not just what it says, but why it was written that way, what it silently commits the rest of the file to, and what a more careful, more experienced version of that same line might look like instead.
1Why Every Dockerfile Needs a Starting Point
Before defining the instruction precisely, it helps to understand the exact gap it fills.
A quick reminder about Dockerfiles and images
A Dockerfile is a plain text file listing, step by step, how to assemble a Docker image, a packaged, read-only bundle containing an application and everything it needs to run. Each step in a Dockerfile is written as an instruction, a single command such as copying in a file, installing a tool, or setting a value. Docker reads these instructions from top to bottom and builds the image one small layer at a time.
But before any instruction can copy a file or install a tool, something has to already exist to copy that file onto, or install that tool into. Nothing in computing truly begins from absolute nothingness. Every image needs a starting point.
A novelist rarely starts a story by describing the invention of language itself. A story simply begins: “It was a rainy Tuesday in a small coastal town.” Everything else builds from that opening sentence. The FROM instruction is a Dockerfile’s opening sentence. It sets the scene that every following instruction takes for granted.
What would happen without a starting point
If a Dockerfile had to describe every single file of an operating system by hand before an application could even be installed, building even a simple website would take an enormous, unreasonable amount of work, and every developer would likely build that foundation slightly differently, quietly breaking the very consistency Docker is famous for. The FROM instruction removes this burden entirely, letting a developer begin from an already-built, already-tested foundation and focus only on what makes their application unique.
One line, an enormous amount of hidden work saved
It is worth pausing on just how much effort a single FROM line quietly represents. Behind that one short line sits the accumulated work of the people who built and maintain the chosen operating system, the people who packaged it specifically for Docker, and often the people who prepared a particular programming language’s runtime on top of it. A developer writing FROM is not skipping a step out of laziness; they are standing on a carefully built foundation prepared by many other people, so that their own attention can go toward the part of the project that is actually new: their own application.
2What Is the FROM Instruction? A Plain Definition
With the motivation clear, here is the precise, plain-English meaning.
A simple definition
The FROM instruction is the line in a Dockerfile that names the base image an image will be built on top of. It is almost always the very first meaningful instruction in the file, and it tells Docker, in effect, “begin here, with this already-prepared foundation, and I will describe everything I want to add on top of it below.”
A base image, the thing that FROM points to, is itself an already-built image, usually containing a small operating system layer, and sometimes a programming language already installed. Every instruction written after FROM in the Dockerfile builds one more layer on top of whatever that base image already provides.
Imagine buying a house that already has a foundation, walls, plumbing, and a roof, and then renovating the inside to your own taste. You do not need to pour a new foundation or rebuild the roof; you simply start from what is already there. FROM is the act of choosing which existing house you are renovating, before you decide what color to paint the kitchen.
Why it must come first
Docker builds an image as a stack of layers, one on top of another, in the exact order the Dockerfile’s instructions appear. Every later instruction, whether it copies in a file or installs a tool, needs somewhere to place that change. Without a base image already established, there would be no foundation to place anything onto. This is why FROM is required near the very top of a Dockerfile, and why leaving it out, or placing meaningful instructions before it, causes Docker to refuse to build the image at all.
There is a small, useful exception worth knowing about: a Dockerfile is allowed to contain certain special comment-like instructions above its first FROM line, used to configure how the build itself behaves before any image is even chosen. These do not add any files or programs of their own; they simply adjust settings for the build process. Everything that actually shapes the final image’s content, however, must still come after FROM, which remains, in every practical sense, where a Dockerfile’s real story begins.
An instruction in a Dockerfile is one single, self-contained step, written as a keyword followed by details, such as FROM, COPY, or RUN. FROM is simply the instruction whose job is choosing the starting base image.
FROM versus every other instruction
Nearly every other instruction in a Dockerfile describes a change: copy this file in, run this command, set this value. FROM is different in kind, not just in position. It does not change anything by itself; it establishes the entire world every later instruction will operate inside. A useful way to picture the difference is that later instructions are verbs, describing actions to take, while FROM is closer to a noun, naming the place where all of those actions will happen. Understanding this distinction helps explain why Docker treats FROM so strictly, requiring it near the top and, in a single-stage Dockerfile, allowing only one of it.
3Core Concepts: The Anatomy of a FROM Line
A FROM line looks short, but each part it can contain carries real meaning. Here is every piece, explained plainly.
Image name
The name of the base image to start from, such as an operating system or a programming language runtime. This is the one part that must always be present.
Tag
A short label marking a specific version of that image, such as “3.19” or “slim.” Without a tag, Docker quietly assumes you mean the tag named “latest,” which is rarely the safest choice.
Digest
A long, unique fingerprint identifying one exact, unchangeable version of an image’s content, even more precise than a tag. Two images with the same digest are guaranteed to be byte-for-byte identical.
A stage name
A short nickname given to that particular FROM line, so a later part of the same Dockerfile can refer back to it by name, rather than by its position in the file.
A registry address
Where the image should be fetched from, if it is not the default public registry, such as a company’s own private, internally hosted image storage.
Tags versus digests, explained with a comparison
A tag is a friendly, human-readable label, similar to how a book edition might be called “second edition, revised.” A digest is closer to that exact edition’s individual printed serial number: unmistakable, but not something a person would casually memorize. Tags are wonderful for everyday communication between developers. Digests are wonderful for guaranteeing that an automated system receives the exact same content every single time, with zero ambiguity.
It is worth noticing that a tag is really only a pointer, not the content itself. The people maintaining a base image can, and sometimes do, move a tag such as “3.19” to point at a newer, slightly updated version of that same image over time, usually to deliver small fixes. A digest, in contrast, is calculated directly from the image’s actual content, so it can never be quietly moved to point somewhere else; if even one byte changes, the digest itself changes along with it. This is exactly why a digest offers the strongest possible guarantee, at the cost of being far less convenient for a human being to read, remember, or type out by hand.
| Way of identifying an image | What it guarantees | Best suited for |
|---|---|---|
| Name only, no tag | Whatever “latest” currently points to, which can silently change over time | Quick, throwaway experiments only |
| Name with a version tag | A specific, human-friendly version, though the exact content behind that tag can still be updated later | Everyday development and most production use |
| Name with a digest | The exact, unchangeable content, byte for byte, forever | Strict, highly repeatable production or compliance requirements |
4What Happens Internally When FROM Runs
Following the exact sequence of events makes the whole mechanism concrete rather than abstract.
sequenceDiagram
participant B as Docker Build
participant L as Local Image Storage
participant R as Registry (e.g. Docker Hub)
B->>L: Is the named base image already stored locally?
L-->>B: Found locally (skip download) or Not found
B->>R: If not found locally, request the base image
R-->>B: Send the base image's layers
B->>B: Place base image layers at the bottom of the new image
B->>B: Continue with the Dockerfile's remaining instructions
Read the sequence from top to bottom. The moment Docker reaches the FROM line, it checks whether that exact base image is already sitting on the local machine from an earlier build. If it is, nothing needs to be downloaded, and the build continues immediately. If it is not, Docker fetches it from a registry, a storage service for images, and only then does it lay that base image down as the bottom layers of the new image being built. Every instruction written after FROM in the file is processed only once this foundation is fully in place.
Why the first build feels slower than later ones
The very first time a new base image is used on a given machine, that download takes real time, sometimes noticeable, depending on its size and the speed of the connection. Every later build that reuses the exact same base image and tag on that same machine skips the download entirely, since Docker keeps a local copy and reuses it. This is one of the quiet reasons an experienced developer’s machine often builds a familiar project far faster than a brand new laptop building it for the very first time.
What happens when the tag changes but the name does not
Because Docker checks for an exact match between the image name and its tag, changing only the tag on a FROM line, even while leaving the image name itself untouched, is treated as an entirely different starting point. If that particular combination has never been fetched on this machine before, Docker downloads it fresh, exactly as it would for a completely unrelated base image. This is a useful detail to remember: from Docker’s point of view, “python, version 3.11” and “python, version 3.12” are two separate, independently stored foundations, not two versions of one single thing sitting on top of each other.
5FROM in Multi-Stage Builds
One of the most powerful, and most commonly misunderstood, uses of FROM appears when it shows up more than once in the very same Dockerfile.
More than one FROM in a single file
A Dockerfile is allowed to contain multiple FROM instructions, one after another, each one starting a brand new, separate stage, a self-contained section of the build. This technique is called a multi-stage build. A common pattern uses one early stage, built from a fuller base image with compilers and build tools, to prepare or compile an application, and then a later, separate stage, built from a second, much smaller base image, into which only the finished, ready-to-run result is copied.
A busy restaurant kitchen is full of mixing bowls, raw ingredients, and cutting boards a customer never sees. Only the finished, plated dish is carried out to the dining room. A multi-stage build works the same way: an early FROM starts the messy “kitchen” stage, full of temporary build tools, and a later FROM starts a clean “dining room” stage, into which only the finished dish, the compiled or prepared application, is carried across.
flowchart LR
F1["FROM (Stage 1: build tools + compiler)"] --> BUILD["Compile / prepare the application"]
BUILD --> COPY["Copy only the finished result across"]
F2["FROM (Stage 2: small, lean base image)"] --> COPY
COPY --> FINAL["Final image — small, ready to run"]
Read the diagram from left to right. The first FROM begins a temporary stage containing everything needed to build the application, including heavy tools that will never be needed once the application is running. The second FROM begins a fresh, separate stage from a much smaller base image. Only the finished output of the first stage is copied into the second, and everything else from that messy first stage, including all its build tools, is left behind entirely, never reaching the final image.
Why naming a stage matters
When a FROM line gives its stage a short nickname, later instructions in the file can refer back to that specific stage by name, rather than by its position, making a Dockerfile with several stages far easier to read and safely rearrange later. Without a name, referring back to an earlier stage still works, but relies on remembering its numeric order, which becomes error-prone as a Dockerfile grows longer.
Later stages can even reuse an earlier stage as their own base
A particularly useful trick is that a later FROM instruction is not limited to naming only a public base image; it can instead name an earlier stage from the very same Dockerfile as its own starting point. This lets a team build a shared, common stage once, perhaps one that installs a set of company-wide tools, and then have several later, more specialized stages each build further on top of that shared stage, rather than repeating the same setup instructions several times over. It is a small feature with an outsized effect on keeping longer Dockerfiles organized and easy to maintain.
Picture a professional kitchen with one shared station where vegetables are always washed and chopped the same careful way, before being sent off to three different chefs preparing three different dishes. Each chef’s dish still ends up unique, but all three save time and stay consistent by starting from that one shared, already-prepared station rather than each washing and chopping vegetables separately from scratch. A shared, reusable stage in a multi-stage Dockerfile plays exactly this role.
6Choosing What Goes After FROM: Advantages, Disadvantages, Trade-offs
The base image named in a FROM instruction is not a small detail. It shapes nearly everything about the final result.
Choosing a fuller base image
- Familiar tools already available for troubleshooting
- Fewer surprises for developers used to a full operating system
- Easier first-time setup for beginners
Choosing a leaner base image
- Smaller final image, faster to download and start
- Fewer installed programs, narrowing possible security weaknesses
- Requires slightly more care, since fewer built-in tools are present for debugging
The trade-off in one sentence
What you name after FROM trades a small amount of convenience for either comfort or leanness, and there is rarely one universally correct answer. A comfortable, tool-rich base image is often the right early choice while a project is still taking shape, and a leaner one is often the right final choice once that same project is heading toward real customers.
A practical pattern: different FROM lines for different stages
Rather than treating this as a single, permanent decision, many teams simply use different base images at different points in a project’s life, exactly as multi-stage builds enable. An early, exploratory FROM line, perhaps pointed at a fuller operating system image, gives developers a comfortable place to experiment while a project’s shape is still uncertain. A later, final FROM line, pointed at a much smaller, leaner image, gives customers and production servers a fast, tight, secure result. Nobody has to permanently pick one side of the trade-off, because the FROM instruction can simply be used more than once, each time suited to the job that particular stage needs to do.
7Security Considerations Around FROM
Because FROM sits at the very bottom of everything, whatever it points to affects the safety of the entire final image.
Everything above FROM inherits what is below it
If the base image named in a FROM instruction contains an outdated tool with a known weakness, every image built from it silently carries that same weakness forward, often without the developer realizing it. This is why the choice made on this one line deserves real attention, not a quick, careless guess.
This inheritance flows only downward, never upward: nothing an application adds later in its own Dockerfile can somehow reach back and repair a flaw sitting inside the base image itself. If a weakness lives in the foundation, the only real fix is choosing a different, corrected foundation, which in practice usually means updating the version named on the FROM line and rebuilding.
Name an exact version tag
Avoid leaving the tag out entirely, since that silently means “latest,” which can change unpredictably from one build to the next.
Prefer official, maintained images
Choose base images actively kept updated by a trusted source, rather than an unknown, possibly abandoned upload.
Consider pinning to a digest for strict cases
For situations demanding absolute, byte-for-byte repeatability, naming an exact digest guarantees the same content every single build, forever.
Rebuild against updated base images regularly
Periodically rebuild against the newest patched version of a chosen base image, so fixes for newly discovered weaknesses reach your application too.
Some newcomers assume that once a Dockerfile is written and working, the FROM line never needs another look. In reality, the base image it names keeps receiving its own updates over time, some of them fixing real security weaknesses. A FROM line written once and never revisited quietly drifts further behind those fixes with every month that passes.
The supply chain hiding behind one short line
A base image named in a FROM instruction is not written by one lone person in an afternoon. It typically passes through many hands: the people maintaining the underlying operating system, the people packaging it specifically for Docker, and the automated systems that rebuild and republish it whenever an important fix is released. This entire chain of people and processes is sometimes called a software supply chain, borrowed from how a physical product travels from raw materials to a finished item on a store shelf. Just as a careful shopper checks where their food comes from, a careful engineering team checks where the image behind its FROM line comes from, favoring sources with a long, visible, trustworthy history over an anonymous upload with no track record at all.
8Design Patterns and Anti-patterns
Years of real-world Dockerfile writing have produced a handful of consistently good habits, and a few well-known traps.
Helpful patterns
One shared, approved FROM target
A company standardizes on one internally approved base image, and every team’s FROM line points to that same trusted source.
Named multi-stage builds
Every stage in a multi-stage Dockerfile is given a clear, descriptive name, making a long build file easy for a newcomer to follow.
Version pinning as policy
A team’s review process specifically checks that every FROM line names an exact version, rather than allowing “latest” to slip through unnoticed.
Anti-patterns to avoid
Leaving the tag out and relying on “latest”
Omitting a version tag after the image name quietly means whatever “latest” happens to point to on that particular day, which can differ between two builds run only weeks apart, breaking the very consistency Docker promises.
Copy-pasting a FROM line without understanding it
Reusing a FROM line found online, without checking whether that base image is trustworthy, maintained, or even still appropriate for the project, can quietly import someone else’s outdated or unsuitable foundation.
Never revisiting an old FROM line
Treating a Dockerfile as finished forever, and never checking whether a newer, better-maintained version of its base image exists, allows a project to fall further and further behind on both features and security fixes.
9Best Practices and Common Mistakes
A practical checklist for writing a FROM line that will not cause trouble later.
| Best practice | Common mistake it prevents |
|---|---|
| Always specify an exact version tag | A build silently changing behavior when “latest” updates underneath it |
| Choose the smallest base image that comfortably fits the job | Bloated final images that are slow to download and deploy |
| Use multi-stage builds to separate building from running | Shipping heavy compilers and temporary build tools to production by accident |
| Name every stage clearly in a multi-stage Dockerfile | Confusing, hard-to-follow files that are risky to modify later |
| Revisit and rebuild against updated base images periodically | Running for months on a base image with known, since-fixed weaknesses |
| Document why a particular base image was chosen | Future teammates guessing, or accidentally swapping it for something worse |
None of these habits take more than a few extra minutes when a Dockerfile is first written, yet skipping them tends to cause exactly the kind of quiet, slow-building trouble that only becomes visible much later, often during an urgent investigation or right before an important launch.
A short story of what happens when a habit is skipped
Consider a small team that writes a Dockerfile quickly under deadline pressure, leaving off the version tag entirely because it seems like a minor detail at the time. For months, builds work perfectly, since the base image behind “latest” happens not to change in any way that affects them. Then, one ordinary morning, the maintainers of that base image publish a new “latest” version containing a small but meaningful behavior change. The very next build, with no code changes on the team’s own side at all, suddenly fails in a way nobody can immediately explain, because nothing in their own Dockerfile appears to have changed. The FROM line itself never failed; it simply did exactly what it was written to do, which was never pin down anything precise in the first place.
10Real-World Stories
The FROM instruction is easiest to appreciate once you see how real, well-known organizations actually treat it.
Docker’s own Official Images program
Docker curates a set of “Official Images” for popular operating systems and languages, and countless organizations point their own FROM lines directly at these reviewed, actively maintained images rather than building an equivalent foundation by hand.
Companies with centrally managed base images
Larger, security-conscious companies commonly maintain their own internal base image, hardened and pre-approved by a central security team, and require every team’s FROM line to point only at that one trusted, internally hosted source rather than the open public internet.
Open-source projects using multi-stage FROM lines
Many popular open-source projects publish Dockerfiles with two or more FROM instructions, one for compiling the project from its source code and a second, much smaller one for the image end users actually download, keeping downloads fast for everyone who simply wants to run the finished software.
Small teams standardizing on one language image
Small engineering teams commonly agree, informally, to always start every service written in a particular programming language from the exact same official runtime image and version, purely so that every project in the company feels familiar and predictable to work on.
Regulated companies pinning by digest
Organizations working under strict compliance or auditing requirements, such as certain financial or healthcare companies, sometimes go a step further than pinning a version tag and pin the exact digest of an approved base image instead, so that auditors can verify, without any ambiguity at all, exactly what content every production system was built from.
11Frequently Asked Questions
12Summary and Key Takeaways
A quick review of everything this guide has covered, ready to keep close at hand.
Key takeaways
- The FROM instruction names the base image that a Dockerfile builds on top of, and it is almost always the very first meaningful line in the file.
- Nothing can be built without a starting point; FROM exists so developers never have to assemble a basic operating system foundation by hand for every project.
- A FROM line can include an image name, a version tag, a digest, a stage name, and a registry address, each one carrying its own precise meaning.
- Leaving the tag out silently means “latest,” which can change unpredictably; naming an exact version keeps builds repeatable.
- Multiple FROM instructions enable multi-stage builds, letting a heavy, tool-rich stage prepare an application while only the finished result is copied into a small, lean final stage.
- Whatever FROM points to, the entire final image inherits, including any security weaknesses, which is why choosing it carefully and revisiting it periodically both matter.
- Real organizations, from Docker’s own Official Images program to companies with centrally managed base images, treat the FROM line as a deliberate, reviewed decision, not an afterthought.
- A FROM line is never truly “set and forget.” The base image it names keeps changing over time, so revisiting it periodically is part of responsibly maintaining any Dockerfile.