Translation(s): none


The Debian /usr Merge

This page tracks Debian support for the merged /usr directories scheme, i.e. the /{bin,sbin,lib}/ directories becoming symbolic links to /usr/{bin,sbin,lib}/.

The usrmerge package will convert the system it is installed on.

For users

You may arrive to this page after seeing this error in apt:

Preparing to unpack .../base-files_13.4_amd64.deb ...
*************************************************************************
*
* The base-files package cannot be installed because
* /bin is a directory, but should be a symbolic link.
*
* Please install the usrmerge package to convert this system to merged-/usr.
*
* For more information please read https://wiki.debian.org/UsrMerge.
*
*************************************************************************

The best explanation of this can be found in the Debian 12 "Bookworm" release notes: https://www.debian.org/releases/bookworm/amd64/release-notes/ch-information.en.html#a-merged-usr-is-now-required

Further documentation will eventually be published in the Debian 13 "Trixie" release notes in 2025.

Resources for developers

Status of the file move moratorium

In the second decision of the CTTE on merged-/usr, it also recommended not moving files between / and /usr. This recommendation is called the file move moratorium. It has since been repealed and delegated to this page. We now encourage moves, subject to caveats below.

Current rules:

Build daemons are /usr-merged since 2023-10-09.

The debian-installer is /usr-merged in git and the archive copy will be on the next upload.

How to move files from / to /usr?

For a lot of packages (about 500 source packages), the only affected files is systemd units. These will be automatically moved via changes in debhelper and systemd.pc. As of now debhelper will install units below /usr and systemd.pc will follow on 2023-11-30. A simple no-change upload or binNMU moves your units. If this applies to you, you may skip over most of this section, but still pay attention to the last paragraph.

Before moving files, please keep in mind that no bookworm suite (and that includes bookworm-backports) should move files to avoid breakage there. So when you look into moving files, the first question to ask is whether you want to support uploads of your package to bookworm-backports. If you do, your packaging should ensure that files continue to be distributed to / and /usr in the same way that they used to be in bookworm. Before dh_installdeb, you may insert dh_movetousr or Build-Depends: dh-sequence-movetousr. This helper is available in bookworm-backports and becomes a no-op there. That said, dh_movetousr is not meant to stay. It encourages maintaining code that becomes dead before too long. If you end up using it, be prepared to remove its use during the forky cycle. If you also want to support backports to bullseye-backports-sloppy, use if command -v dh_movetousr >/dev/null; then dh_movetousr; fi.

If you have aliased systemd units that are manually installed, consider letting dh_installsystemd install them as it will also undo the move in bookworm-backports. In 3.0 source package, debian/somepkge.service may be a symbolic link pointing at location in the upstream source and will correctly be installed.

If you do not want to support uploads to bookworm-related suites such as bookworm-backports, manually moving the files may provide a simplification in packaging. Sometimes, it amounts to removing an existing --prefix=/ and reverting to the default --prefix=/usr. Often times, a package's files have been split to / and /usr in a manual way and this can now be removed. When you do, please check all debian/*.install, debian/*.links and debian/*.dirs files and review that your package does not contain an empty /bin, /lib or /sbin directory.

Regardless of how you perform the move, please upload to experimental. A tool called dumat will analyze your package for some classes of known problems and shall get back to you within three days via the bug tracking system in the event of problems. DEP17 provides a collection of known problem classes. Of these, dumat will check for P1, P2, P3 (mostly), P6, and P7. Problems P8, P9 and P10 are mostly relevant to packages close to the essential set. Affected packages have received instructions or patches. When in doubt, consider asking Helmut. Please check for the following problems before your upload:

In general, we try to handle the more complex cases by sending patches.

After having successfully moved files from / to /usr, there is one more task. Any restructuring change to your package during the trixie cycle should be uploaded to experimental with a three day grace period to detect problems. A restructuring change is renaming a package (for instance adding a t64 suffix for the 2038 transition) or moving a file from one binary package to a different binary package (from the same source package or a different source package).

Can I simply move systemd units to /usr/lib/systemd even in older releases?

Unfortunately, no. If the unit existed earlier in /lib/systemd, moving it to /usr/lib/systemd is prone to loss. So please do not move units from in a backport or stable update. For another dh_installsystemd generates maintainer scripts for installed units. Before trixie it only generates maintainer scripts for units installed to /lib/systemd and not for units installed to /usr/lib/systemd.

Transition priorities

This section is for people working on the transition beyond their own packages. We have a few areas of work.

Important packages and filesystem bootstrap

The target of this work is to get the aliasing symlinks into base-files. To get there we first have to move files in most important packages. Once only the exception are left, there will be a coordinated upload. This work is coordinated with Helmut Grohne and has high risk of fallout. Please refrain from uncoordinated uploads. The intention is to finish this by the end of March 2024.

udev

The moving of udev rules turns out to affect rather more packages. Therefore, dh_installudev and udev.pc now point below /usr, but a lot of packages hardcode the old paths. Patches are being sent to update these packages, but please also work on this directly in the packages you are maintaining. At a later time, binNMUs or new uploads will convert the remaining udev locations.

Previously, some packages would encounter M-A:same shared file loss (P7), but these have been fixed in the meantime.

diversion mitigation

It turned out that the initial version of M18 did not work at all. We are developing a new one on molly-guard. Until this is validated, we should not touch further diversions as we cannot ensure to fix them in a timely manner. This work is driven by Helmut Grohne.

Move files to /usr in other packages

In effect, this is working on the long-tail of the transition and both serves reducing the size of the transition and in discovering unforeseen problems sooner rather than later. So just converting random packages and figuring out how that does not work is a useful thing to do at this time. This is not coordinated. Please report problems to Helmut Grohne. The intention is to finish this by the start of the transition freeze.

FAQ

For more information, please refer to the usrmerge package FAQ, another highly recommended read is <20181121140542.GA31273@espresso.pseudorandom.co.uk>

Is this about merging /usr/bin/ and /usr/sbin/?

No, there are no plans to do that.

Will switching to a merged /usr be mandatory?

In February 2021, the Technical Committee has resolved that Debian 'bookworm' should support only the merged-usr root filesystem layout, dropping support for the non-merged-usr layout. (978636)

The transition started on September 17th, 2022, by making init-system-helpers depend on usrmerge.

usrmerge is uninstallable, what do I do?

You might have run a script that installs a blocker metapackage. It needs to be removed manually, then apt will be able to upgrade the system:

Adoption rate

debootstrap has supported a --merged-usr option since version 1.0.83, and this has been the default since version 1.0.85. The default was reverted in 1.0.87 and re-enabled in 1.0.102. A --no-merged-usr option is also available.

See popcon for upgrades of older systems.

Affected packages using dpkg-statoverride

Querying statoverride on path in /bin:

Querying and managing statoverride on path in /sbin:

User-tagged bugs:

See also