docker build Command Reference
Build an image from a Dockerfile and a build context
Syntax
The docker build command builds Docker images from a Dockerfile and a "context". A build's context is the set of files located in the specified PATH or URL. The build process can refer to any of the files in the context.
The docker build command is one of the most fundamental commands in Docker. It creates an image from a Dockerfile and a build context. The command performs the build steps in the Dockerfile, resulting in a new image that can be used to create containers.
Description
The docker build command builds an image from a Dockerfile and a context. The build context is the set of files at a specified location PATH or URL. The PATH is a directory on your local filesystem. The URL is a Git repository location.
A context is processed recursively. So, a PATH includes any subdirectories and the URL includes the repository and its submodules. The build is run by the Docker daemon, not by the CLI. The first thing a build process does is send the entire context (recursively) to the daemon. In most cases, it's best to start with an empty directory as context and keep your Dockerfile in that directory. Add only the files needed for building the Dockerfile.
The Docker daemon uses the files in the context to build the image, and it cannot access files outside the context.
You can specify a repository and tag at which to save the new image if the build succeeds:
docker build -t username/app:1.0 .To create a build with multiple tags for the same image:
docker build -t username/app:1.0 -t username/app:latest .The Docker daemon runs the instructions in the Dockerfile one-by-one, committing the result of each instruction to a new image if necessary, before finally outputting the ID of the new image. The Docker daemon automatically cleans up the context it received when the build is done.
Examples
Basic Build
Build an image from a Dockerfile in the current directory:
docker build -t myapp .This builds an image using the Dockerfile in the current directory and tags it as "myapp".
Building with a Specific Dockerfile
Build using a specific Dockerfile:
docker build -f Dockerfile.production -t myapp:prod .This builds an image using "Dockerfile.production" and tags it as "myapp:prod".
Building with Build Args
Pass build arguments to the build process:
docker build --build-arg ENV=production --build-arg VERSION=1.0.0 -t myapp:1.0.0 .This builds an image with build-time variables ENV and VERSION.
Multi-stage Build with Target
Build a specific stage of a multi-stage Dockerfile:
docker build --target development -t myapp:dev .This builds an image up to the development stage in a multi-stage Dockerfile.
Building with Cache Sources
Use another image as a cache source:
docker build --cache-from myapp:previous -t myapp:latest .This builds an image using cached layers from the myapp:previous image.
Building from a Git Repository
Build directly from a Git repository:
docker build -t myapp https://github.com/username/repository.git#mainThis builds an image from the main branch of the specified Git repository.
Building for a Specific Platform
Build an image for a specific platform:
docker build --platform linux/arm64 -t myapp:arm64 .This builds an image specifically for the ARM64 architecture.
Building with SSH Authentication
Build with SSH authentication for private repositories:
docker build --ssh default -t myapp .This builds an image with SSH authentication forwarded to the build process.
Best Practices
- Use a .dockerignore file to exclude files and directories that aren't needed for the build, reducing build context size and improving performance.
- Tag your images properly with meaningful names and versions to maintain organization.
- Use build caching to speed up builds by properly ordering your Dockerfile instructions.
- Use multi-stage builds to create smaller, more efficient images.
- Keep build contexts as small as possible to improve build speed and reduce resource usage.
- Use BuildKit to take advantage of improved caching, parallel processing, and other performance features.
- Regularly inspect your image sizes to identify opportunities for optimization.
- Use CI systems to automate builds and ensure consistency.
Notes and Limitations
- The build context is sent to the Docker daemon, so avoid including large or unnecessary files.
- By default, Docker will look for a file named "Dockerfile" at the root of the build context.
- The Docker daemon runs the instructions in the Dockerfile one-by-one, committing the result to a new image if necessary.
- Each instruction creates a new layer in the image, contributing to the final size.
- BuildKit is available as an alternative builder backend that offers more features and better performance.
- Build cache is preserved by default between builds to speed up repeated builds.
- Build arguments (--build-arg) are only available during the build process and not in the running container unless explicitly set as environment variables.