Wolfi is the first community Linux (un)distribution declaratively built for creating a secure base layer for your containers!
Wolfi is a Linux OS designed for the container and cloud-native era. Chainguard started the Wolfi project to enable building Chainguard Containers, our collection of curated distroless images that meet the requirements of a secure software supply chain. This required a Linux distribution with components at the appropriate granularity and with support for glibc.
Wolfi is a stripped-down distro designed for the cloud-native era. It doesn't have a kernel of its own, instead relying on the environment (such as the container runtime) to provide one. This separation of concerns in Wolfi means it is adaptable to a range of environments.
Wolfi, whose name was inspired by the world's smallest octopus, has some key features that differentiates it from other distributions that focus on container/cloud-native environments:
- Provides a high-quality, build-time SBOM as standard for all packages
- Packages are designed to be granular and independent, to support minimal images
- Focuses on the latest release of all packages
- Uses the proven and reliable apk package format
- Fully declarative and reproducible build system
- Designed to support glibc
The os repository contains the core Wolfi OS as a sync from internal Chainguard repositories. Any proposed improvements are applied internally, and then synced back out to the public repository.
| Resource | Details |
|---|---|
| Forum | See GitHub Discussions |
| Slack | Some community members can be found in the#apko channel on Kubernetes Slack, but there is no active monitoring of this channel. |
| Slack | Some community members can be found on Chainguard Community Slack |
The community repo contains full details of past community calls and resources.
To get you up and running with Wolfi, let's go over a quick demo where you can create an image from a Dockerfile.
We'll use a "Hello, World" style Python program to demonstrate:
def main():
print("Hello, Wolfi!")
if __name__ == "__main__":
main()Within the same directory, you can create the Dockerfile. This Dockerfile will set up the WORKDIR, and copy relevant files. It will also define the entry point that will be executed when we run this image with docker run. We are using the wolfi-base image to build a Python image from scratch, using Wolfi apks. The final image runs using the unprivileged nonroot user.
FROM cgr.dev/chainguard/wolfi-base
ARG version=3.11
WORKDIR /app
RUN apk add python-${version} && chown -R nonroot:nonroot /app/
USER nonroot
COPY hello_wolfi.py /app/
ENTRYPOINT [ "python", "hello_wolfi.py" ]
This Dockerfile uses a variable called version to define which Python version is going to be installed on the resulting image. You can change this to one of the available Python versions on the wolfi-dev/os repository.
From here, you can build and run your image. If you run into issues with the build step, try using sudo.
docker build . -t hellowolfi
docker run --rm hellowolfiYou should receive the following output:
Hello, Wolfi!
For more guidance, you can check out a full tutorial on Creating Wolfi Images with Dockerfiles, or alternately use apko to build a distroless image with only the packages you need, by reviewing a Getting Started with apko tutorial.
Wolfi is a Linux undistro designed from the ground up to support newer computing paradigms such as containers. Although Wolfi has a few similar design principles as Alpine (such as using apk), it is a different distribution that is focused on supply chain security. Unlike Alpine, Wolfi does not currently build its own Linux kernel, instead relying on the host environment (e.g. a container runtime) to provide one.
Yes, Wolfi is freely available under the Apache License V2 and will always be.
Packages in Wolfi are published to public Wolfi APK Repositories.
Wolfi focusses on latest package versions and provides a base minimum of packages for variety of containers. Specifically all packages used in free Chainguard Containers are available as packages.
Non-latest versions of packages in these repositories are retained for 12 months until June 8th, 2026, and then for 6 months by default.
For more information, see the Wolfi Archive Policy announcement, the updated policy announcement, and our discussions forum in general.
Chainguard also regularly removes packages from Wolfi for reasons outside the scope of the Wolfi retention policy. Typically, this involves removing the package definition from the Wolfi GitHub repository only.
Existing packages that have already been built remain in the Wolfi binary package repository such as apk.cgr.dev/chainguard/x86_64 until they are removed according to the retention policy.
The most common trigger for removal is when a new version of a version streamed package is released. In this situation, package definitions for prior versions streams are removed from Wolfi. For example, when MariaDB 13 is released and added to Wolfi, MariaDB 12 is removed from Wolfi. New versions of MariaDB 12 packages are available from Chainguard only as the focus of Wolfi is on latest releases only.
No, it’s not possible to mix Alpine apks with Wolfi apks. If your image requires dependencies that are currently only available for Alpine. You might consider using melange to build a custom apk for your image.
No. Desktop distributions require additional software that is out of scope for Wolfi.
Wolfi was created and is currently maintained by Chainguard as the base of Chainguard OS.
We intend for Wolfi to be the core foundation of Chainguard OS and available as open source project for use with minimal packages as used in our free Chainguard Containers.
See SECURITY.md for information about reporting security incidents concerning and consuming security data about Wolfi.
Find details in our repositories, use our community channels and read our documentation.
