Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?


Failed to load latest commit information.
Latest commit message
Commit time
March 31, 2023 12:47
June 28, 2023 15:53
September 22, 2023 14:31
February 15, 2023 10:35
September 20, 2023 11:28
March 4, 2022 21:16
September 14, 2022 19:39
September 29, 2022 15:53
February 23, 2022 20:41
September 15, 2023 17:01
February 8, 2022 11:04
August 2, 2023 15:21
May 19, 2023 16:40
April 30, 2023 22:31
September 19, 2023 10:09
September 19, 2023 10:09

apko: apk-based OCI image builder

Build and publish OCI container images built from apk packages.

apko has the following key features:

  • Fully reproducible by default. Run apko twice and you will get exactly the same binary.
  • Fast. apko aims to build images in ms.
  • Small. apko generated images only contain what's needed by the application, in the style of distroless.
  • SBOM Support. apko produces a Software Bill of Materials (SBOM) for images, detailing all the packages inside.
  • Services. apko supports using the s6 supervision suite to run multiple processes in a container without reaping or signalling issues.

Please note that apko is a work in progress and details are subject to change!


You can install apko from Homebrew:

brew install apko

You can also install apko from source:

go install

You can also use the apko container image:

docker run version

To use the examples, you'll generally want to mount your current directory into the container, e.g.:

docker run -v "$PWD":/work build examples/alpine-base.yaml apko-alpine:edge apko-alpine.tar

Alternatively, if you're on a Mac, you can use Lima to run an Alpine Linux VM.


An apko file for building an Alpine base image looks like this:

    - alpine-base

  command: /bin/sh -l

# optional environment configuration
  PATH: /usr/sbin:/sbin:/usr/bin:/bin

We can build this with apko from any environment with apk tooling:

apko build examples/alpine-base.yaml apko-alpine:test apko-alpine.tar
2022/04/08 13:22:31 apko (aarch64): generating SBOM
2022/04/08 13:22:31 building OCI image from layer '/tmp/apko-3027985148.tar.gz'
2022/04/08 13:22:31 OCI layer digest: sha256:ba034c07d0945abf6caa46fe05268d2375e4209e169ff7fdd34d40cf4e5f2dd6
2022/04/08 13:22:31 OCI layer diffID: sha256:9b4ab6bb8831352b25c4bd21ee8259d1f3b2776deec573733291d71a390157bb
2022/04/08 13:22:31 output OCI image file to apko-alpine.tar

or, with Docker:

docker run -v "$PWD":/work build examples/alpine-base.yaml apko-alpine:test apko-alpine.tar

You can then load the generated tar image into a Docker environment:

docker load < apko-alpine.tar
Loaded image: apko-alpine:test
docker run -it apko-alpine:test
e289dc84c4ad:/# echo boo!

You can also publish the image directly to a registry:

apko publish examples/alpine-base.yaml myrepo/alpine-apko:test

See the docs for details of the file format and the examples directory for more, err, examples!

Debugging apko Builds

To include debug-level information on apko builds, add --debug to your build command:

docker run --rm -v ${PWD}:/work build --debug \
  apko.yaml hello-minicli:test hello-minicli.tar \


apko was created by Chainguard, who require secure and reproducible container images for their tooling. Speed is also a critical factor; Chainguard require images to be rebuilt constantly in response to new versions and patches.

The design of apko is heavily influenced by the ko and distroless projects.

Declarative Nature

By design, apko doesn't support an equivalent of RUN statements in Dockerfiles. This means apko files are fully declarative and allows apko to make stronger statements about the contents of images. In particular, apko images are fully bitwise reproducible and can generate SBOMs covering their complete contents.

In order to install bespoke tooling or applications into an image, they must first be packaged into an apk. This can be done with apko's sister tool melange.

The combination of melange and apko cover the vast majority of use cases when building container images. In the cases where they are not a good fit, our recommendation is to build a base image with apko and melange, then use traditional tooling such as Dockerfiles for the final step.

Support and Further Reading

Tutorials and guides for apko can be found at the Chainguard Academy.

For support, please find us on the Kubernetes Slack in the #apko channel or open an issue.

The melange project is designed to produce apk packages to be used in apko.

The ko project builds Go projects from source in a similar manner to apko.

The service creates fresh container images on demand using different forms of declarative configuration (including ko and apko).