UsrMerge - Debian Wiki

UsrMerge - Debian Wiki
Wiki
FrontPage
RecentChanges
FindPage
HelpContents
UsrMerge
Wiki
Comments
Info
Attachments
UsrMerge
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:
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:
Do not move files from
/usr
to
We want
/bin
/lib
and
/sbin
to become empty. The direction of move is the wrong one.
Do not add new files into
/bin
/lib
/sbin
All packages containing diverted files or adding diversions should have their upgrades tested. Most have already been moved and the remaining ones have received patches. When in doubt, please request help.
Transitively essential packages and
Priority: required
packages must extensively test moving files from
to
/usr
These packages are relevant to filesystem bootstrap and need to work with
debootstrap
cdebootstrap
and
mmdebstrap
all of which work subtly different until we finish the move. Also
bullseye
still has
debootstrap
that merges in a different way but is being updated via o-p-u.
systemd
units and
udev
rules must be moved from
/lib
to
/usr/lib
in all packages (including essential and required):
dh_installsystemd
generates maintainer scripts for
systemd
units below
/usr/lib
since version
13.11.6
. Please add
Build-Depends: debhelper (>= 13.11.6)
Any
debian/*.service
and
debian/*.udev
files are now installed to
/usr/lib
. Your next upload will move them automatically.
Any units installed by an upstream build system to
systemd_system_unit_dir
as discovered using
pkgconf
will already install into
/usr/lib
. If you use this variable, ensure that you do not hard code
/lib/systemd/system
in
debian/*.install
files.
Any files installed by an upstream build system to
udevdir
from
udev.pc
will already into
/usr/lib
. Again, do not hardcode
/lib/udev
in
debian/*.install
files.
Upload restructuring changes to
experimental
first and wait three days:
Doing so gives the
dumat service
an opportunity to file a bug in case your change causes one of the problems from DEP17.
This only applies if the restructured package installed to
/bin
/lib
or
/sbin
in
bookworm
or
trixie
Do not update calls to
update-alternatives
Even if you move e.g.
/bin/more
to
/usr/bin/more
, do not change the location used in the
update-alternatives
invocation. The paths passed to
update-alternatives
are API and changing them would break API. Changing them would also be prone to loss of user preference.
If you add new
alternatives
, install them to
/usr
if possible.
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:
P3: Does your package employ non-default diversions? If you unconditionally use
dpkg-divert
, dumat shall notice. It may fail to notice non-default diversions behind e.g.
debconf
questions. If those diversions interact with aliased locations, action is needed. Please get in touch with Helmut.
P4: Even when changing all aliased paths from / to /usr, you must not change the paths passed to
update-alternatives
invocations that already existed in
bookworm
. The current plan is to keep existing alternatives aliased as a legacy forever and add new alternatives without aliasing.
P5: If your package uses
dpkg-statoverride
, the paths may have to be updated. The old statoverride should be removed and the new one should be added.
P7: While
Multi-Arch: same
shared file loss is detected by dumat, you may mitigate it immediately. If affected, the
dumat.yaml
report shall contain a "risky m-a:same shared file". Chris Hofstaedtler wrote an
example to copy from
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:
# apt install usrmerge
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
Some packages could not be installed. This may mean that you have
requested an impossible situation or if you are using the unstable
distribution that some required packages have not yet been created
or been moved out of Incoming.
The following information may help to resolve the situation:
The following packages have unmet dependencies:
dpkg-fsys-usrunmess : Conflicts: usrmerge
E: Error, pkgProblemResolver::Resolve generated breaks, this may be caused by held packages.
# dpkg --remove --force-all dpkg-fsys-usrunmess
dpkg: warning: overriding problem because --force enabled:
dpkg: warning: this is a protected package; it should not be removed
(Reading database ... 26987 files and directories currently installed.)
Removing dpkg-fsys-usrunmess (1.21.9) ...
# apt install usrmerge
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
The following NEW packages will be installed:
usrmerge
0 upgraded, 1 newly installed, 0 to remove and 0 not upgraded.
Need to get 13.0 kB of archives.
After this operation, 39.9 kB of additional disk space will be used.
Get:1 http://deb.debian.org/debian sid/main amd64 usrmerge all 31 [13.0 kB]
Fetched 13.0 kB in 0s (264 kB/s)
debconf: delaying package configuration, since apt-utils is not installed
Selecting previously unselected package usrmerge.
(Reading database ... 26988 files and directories currently installed.)
Preparing to unpack .../archives/usrmerge_31_all.deb ...
Unpacking usrmerge (31) ...
Setting up usrmerge (31) ...
The system has been successfully converted.
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:
fuse
fuse3
ntfs-3g
Querying and managing statoverride on path in /sbin:
yp-tools
Developer Links
Current dumat output, but note that you should automatically get bugs if your packages are affected
DEP17
User-tagged bugs:
M2 Bugs
P7 Bugs
See also
The Case for /usr Merge.
Fedora: move all to /usr.
Understanding the bin, sbin, usr/bin, usr/sbin split.
UsrMerge (
last modified 2024-08-06 08:51:45
Changes made after 24 July 2025 00:00 UTC are available under
Creative Commons Attribution-ShareAlike 4.0 International
unless otherwise noted.
Debian
, Wiki
team
bugs
and
config
MoinMoin
and
Python
, with hosting provided by
Metropolitan Area Network Darmstadt