Skip to content


Wolfi OS github home.

wolfi logo wolfi logo

Wolfi OS

Wolfi is the first community Linux (un)distribution declaratively built for creating a secure base layer for your containers!

Wolfi is a community Linux OS designed for the container and cloud-native era. Chainguard started the Wolfi project to enable building Chainguard Images, 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 Features

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
  • Uses the proven and reliable apk package format
  • Fully declarative and reproducible build system
  • Designed to support glibc

Where's the Source?

  • os contains the core Wolfi OS repository.

Wolfi Community

The community repo contains full details of our regular community calls, support forums and social media presence.

Resource Details, Links, etc.
Notes View our notes from community meetings
YouTube View our playlist of recorded community meetings
Twitter / X @wolfi_os
Slack #apko channel on Kubernetes Slack
Forum See GitHub Discussions

Get Started

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__":

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.


ARG version=3.11

RUN apk add python-${version} && chown -R nonroot.nonroot /app/

USER nonroot

COPY /app/
ENTRYPOINT [ "python", "" ]

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 hellowolfi

You 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.


What is Wolfi and how does it compare to Alpine?

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.

Is Wolfi free to use?

Yes, Wolfi is free and will always be.

Can I mix packages from Alpine repositories into a Wolfi-based image?

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 opening a new issue in the wolfi-os repository to suggest the new package addition, or use melange to build a custom apk for your image.

Can I use Wolfi on the Desktop?

No. Desktop distributions require additional software that is out of scope for Wolfi's roadmap.

Who maintains Wolfi?

Wolfi was created and is currently maintained by Chainguard.

What are the plans for long-term Wolfi governance?

We intend for Wolfi to be a community-driven project, which means over time it will have multi-vendor governance and maintainers. For now we're focused on building the project and community, and will revisit this in several months when a community has formed.

Where can I get security feeds for Wolfi?

See for information about reporting security incidents concerning and consuming security data about Wolfi.

Where can I ask questions or learn more about using Wolfi?

We have a monthly community call on the 1st Wednesday of every month! Join the next meeting by following Wolfi’s public calendar, or submit your question to our GitHub Community discussions forum.


  1. os os Public

    Main package repository for production Wolfi images

    Shell 614 143


Showing 10 of 16 repositories

Most used topics