Wolfi Moves to usrmerge Standard

To enhance standardization and compatibility with modern Linux applications and other major distributions, Chainguard is adopting the usrmerge filesystem layout. This layout consolidates binaries and libraries into the /usr directory structure. 

This announcement provides our customers and end users with information about the change and what to do in case you have modified container images from Chainguard.

Update May 21, 2025: Chainguard is finalizing the adoption of the “usrmerge” filesystem layout, focusing on libraries. We started this process in March to enhance standardization and compatibility with modern Linux applications and other major distributions. This blog provides more details on the final actions you'll need to take.

What is usrmerge?

Usrmerge refers to the adoption of a filesystem layout where legacy directories, such as /bin, /sbin, /lib are replaced with symlinks to their new locations under /usr, such as /usr/bin and /usr/lib.

Every other enterprise distro, including RHEL, CentOS, SUSE, Ubuntu, and Debian all have utilized usrmerge for nearly a decade. Alpine does not, but has plans to adopt in the future.

What is Chainguard doing?

We are moving the contents of /sbin, /usr/sbin and /bin into /usr/bin, and libraries from /lib into /usr/lib; and corresponding symlinks.

This will be done in 4 different stages, starting with /sbin, followed by /bin, /usr/sbin and finishing with /lib.

Why is Chainguard doing this?

We’re making this change to standardize and for compatibility, because many modern Linux applications expect usrmerge filesystem locations. 

At Chainguard, we haven’t adopted a specific filesystem layout until now. As a result, we did not enforce usrmerge guidelines. This has translated into some packages and images shipping files (binaries or libraries) in legacy directories, while others used the  usr directories that are often required for the creation of symlinks for compatibility with usrmerge.

As we continue to expand our catalog, we believe that standardization and compatibility is key for more sustainability across our container images going forward and so our users know what to expect.

When is Chainguard doing this?

We started the transition on March 3, 2025 and the 4-stage transition (/sbin, /bin, /usr/sbin, /lib) was scheduled to be completed by March 24th, 2025. Thus far, /sbin and /usr/bin, and /usr/sbin have been completed. The final stage of the migration (/lib) will be completed on June 23, 2025.

How will this affect Chainguard users?

Other than underlying image changes, we expect little to no impact to our customers and users:

• Images created before the start of the transition will not be impacted at all.

• Images created after the transition will have binaries or libraries shipped in usrmerge locations with appropriate symlinks back.

• Images that include “apk-tools” will ship with a patched version that includes support for usrmerged lib locations.

If you use “apk add” in your Dockerfiles:

• APK should resolve to a package revision previous to its usrmerge transition, while the transition is incomplete (and you have a non-usrmerge image).

• APK should resolve to a package revision of a usrmerge package after the transition is complete (and you have a usrmerge image).

If you use Chainguard tools, please update to the versions listed below (or greater) before this transition to avoid issues. Existing and new tools will continue to work for existing workflows.

• apko >= v0.27.6

• melange >= v0.23.15

• rules_apko for bazel >= v1.5.3

Any other recommendations?

• Avoid using apk add <package>=<version> and apk upgrade to force the installation of any packages being transitioned, including wolfi-baselayout.

  • As of today, apk add cannot assure package interdependence with those available within the image, even before this transition.

  • We discourage the usage of apk upgrade.

  • If you attempt to add or upgrade new usrmerged packages during or after this transition, this may result in:

    • Packages being unable to install, or

    • Packages being installed with errors, at which point we cannot assure they will work as expected.

• A patched version of apk-tools v2.14.10-3 is provided to handle the transition when using “apk –initdb”

  • This version is compatible with both new and old filesystem layouts.

• Ensure you are not moving binaries, libraries or creating symlinks to usrmerged locations in your Dockerfiles. These practices can sometimes lead to unexpected issues and lead to unsupported scenarios. If you have any questions, feel free to ask!

Where to find additional updates:

Chainguard engineers are keeping this GitHub discussion updated with our progress. You can also find more information for customers in this mitigation knowledge base article and additional notices at  support.chainguard.dev.