docker compose build Command Reference

By Kaveh Alemi·Latchkey

Build the images for services defined in a compose file.

docker compose build builds (or rebuilds) the images for services that have a build section. It is separate from up so CI can build images in one step, then start them in another, or build without starting anything.

Common flags

• --no-cache - build without using the layer cache
• --pull - always pull a newer base image
• --build-arg KEY=value - pass a build-time ARG
• --progress - output style, e.g. plain for full CI logs
• Positional service names limit the build to those services

Example

docker compose build --pull --build-arg NODE_ENV=production app worker
docker compose up -d --wait

In CI

Use --progress plain so BuildKit emits full, non-collapsed logs that are readable in CI output. Building explicitly before up makes the build step a distinct, cacheable stage; --pull keeps base images patched on scheduled builds.

Key takeaways

• compose build creates service images without starting containers.
• --progress plain gives readable, uncollapsed BuildKit logs in CI.
• Name services to build only a subset of the compose file.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation