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.

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. The overall process is expected to take 3 weeks.

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.

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

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.

• 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 and additional notices at support.chainguard.dev.