Skip to content

Rework the descriptions of directories for shared libraries and the symlinks to them #218

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
keszybz wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Rework the descriptions of directories for shared libraries and the symlinks to them #218

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
ad0cb14
lfsh: rewrite the description of directories for shared libraries
keszybz Jun 17, 2026
194ea51
lfsh: fix descriptions of /lib and /lib64 symlinks
keszybz Jun 17, 2026
6b6723c
lfsh: do not recommend multiarch over multilib
keszybz Jun 17, 2026
c73cc08
lfsh: describe the different versions of multilib
behrmann Jun 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
134 changes: 81 additions & 53 deletions specs/linux_file_system_hierarchy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -231,7 +231,9 @@ or in a subdirectory.
Using a subdirectory is recommended if the package installs multiple files.
It is also necessary if multiple versions of the same headers shall be coinstallable.
The subdirectory may be named after the package or project providing it.
Packages may place architecture-dependent header files and directories in a

If the multiarch layout is used,
packages may place architecture-dependent header files and directories in a
`/usr/include/<arch-id>/` subdirectory,
following the identifiers defined on the
[Multiarch Architecture Specifiers (Tuples)](https://wiki.debian.org/Multiarch/Tuples)
Expand All @@ -250,60 +252,85 @@ The corresponding library or libraries shall be placed in `$libdir`, see below.
### Libraries, system programs, and program assets

This section describes the directories used to store shared libraries,
internal binaries or other programs that are not regularly invoked from a shell
internal binaries and other programs that are not regularly invoked from a shell
(and thus should not be placed in the directories in `$PATH`),
and other static files that are part of program installations.
as well as other static files that are part of program installations.

There are two main schemes for shared libraries.
On "multiarch" systems,
multiple different architecture and ABI variants can be installed in parallel.
Each variant uses a hierarchy of files under a directory named using the
[Multiarch Architecture Specifiers (Tuples)](https://wiki.debian.org/Multiarch/Tuples)
list.
multiple different architecture and ABI variants can be installed in parallel,
using subdirectories for different architectures.
On "multilib" systems,
a simpler scheme is used that only supports 32-bit and 64-bit variants of the same architecture.

Both schemes are widely used, and distributions typically choose one or the other.
Multiarch is the recommended approach, especially for new systems.

Note that many locations described in this section
are under shared ownership,
with multiple different packages installing and consuming resources
on equal footing without any obvious primary owner,
and are subject to specifications that ensure interoperability.

#### `/usr/lib/`
and are subject to further specifications to ensure interoperability.

Static, private vendor data that is compatible with all architectures
(though not necessarily architecture-independent).
Note that this includes
internal binaries or other programs that are not regularly invoked from a shell.
Such binaries may be for any architecture supported by the system.
#### Multiarch systems

In the multilib scheme,
32-bit libraries are placed directly in this directory.
In the multiarch scheme,
libraries should not be placed directly in this directory,
but in `$libdir` (see below), instead.

#### `/usr/lib/<arch-id>/`

Location for dynamic libraries, also called `$libdir`.
The "multiarch" layout is used primarily by the Debian family of distributions.
In this layout, shared libraries are stored in subdirectories of `/usr/lib/`,
with files for architecture `<arch-id>` in a hierarchy under the directory `/usr/lib/<arch-id>/`.
This allows files for multiple architectures to be installed in parallel.
The architecture identifier to use is defined on the
[Multiarch Architecture Specifiers (Tuples)](https://wiki.debian.org/Multiarch/Tuples)
list.
Those directories are used on multiarch systems.

On multilib systems,
`/usr/lib/` and `/usr/lib64/` are used instead,
and one of them is `$libdir`.
##### `/usr/lib/`

The top-level `/usr/lib/` directory contains
architecture-independent files,
and internal binaries and other programs that are not regularly invoked from a shell
compiled for the the primary architecture of the system.

##### `/usr/lib/<arch-id>/`

A hierarchy of directories containing shared libraries for architecture `<arch-id>`
and other architecture-dependent files.

#### Multilib systems

The "multilib" layout is used by most other distributions,
in particular all that are RPM-based.
This layout supports parallel installation of 32-bit and 64-bit variants of the same architecture.

##### `/usr/lib/`

This directory contains architecture-independent files,
internal binaries and other programs that are not regularly invoked from a shell,
and shared libraries for either the 32-bit or 64-bit architecture.

##### `/usr/lib64/` or `/usr/lib32/`

This directory can be used for architecture-dependent package-specific data too.
This directory contains shared libraries for the other architecture.

The primary architecture of the system (`$libdir`) may be queried with:
Either directory can be used for architecture-dependent package-specific data too.

###### `/usr/lib64/`

If `/usr/lib/` contains files for the 32-bit architecture,
`/usr/lib64/` may exist and contain files for the 64-bit architecture

###### `/usr/lib32/`

If `/usr/lib/` contains files for the 64-bit architecture,
`/usr/lib32/` may exist and contain files for the 32-bit architecture.

#### The directory for shared libraries for the primary architecture

The directory for shared libraries for the primary architecture is called `$libdir`
and may be queried with:

systemd-path system-library-arch

On multiarch systems this will point to one of the `/usr/lib/<arch-id>` directories,
and either `/usr/lib/` or `/usr/lib64/` on multilib systems.

#### `/usr/libexec/` ⚠️

A secondary location for
Expand Down Expand Up @@ -497,17 +524,18 @@ correctly find their binaries.

### `/lib/`

This compatibility symlink points to `/usr/lib/`,
ensuring that programs referencing this legacy path
correctly find their resources.
A symlink required for the correct execution of binaries specifying
the dynamic loader with a path starting with `/lib/`.
This symlink points to `/usr/lib/`.

### `/lib64/`

On some architecture ABIs, this compatibility symlink points to `$libdir`,
ensuring that binaries referencing this legacy path
correctly find their dynamic loader.
This symlink only exists on architectures whose ABI
places the dynamic loader in this path.
A symlink required for the correct execution of binaries specifying
the dynamic loader with a path starting with `/lib64/`.
The directory to which it points varies between multiarch and multilib installations
and even between different distributions using the multilib layout.
This symlink may not exist on architectures whose ABI
does not place the dynamic loader in this path.

### `/var/run/`

Expand Down Expand Up @@ -554,16 +582,15 @@ Care should be taken when placing architecture-dependent binaries in this place,
which might be problematic if the home directory is shared
between multiple hosts with different architectures.

### `~/.local/lib/`

Static, private vendor data that is compatible with all architectures.

### `~/.local/lib/<arch-id>/`
### User's libraries, system programs, and program assets

Location for placing public dynamic libraries.
The architecture identifier to use is defined on
[Multiarch Architecture Specifiers (Tuples)](https://wiki.debian.org/Multiarch/Tuples)
list.
A private set of directories that mirrors
the directories described for the system in
[Libraries, system programs, and program assets](#libraries-system-programs-and-program-assets)
is defined for the user under `~/.local/`:
`~/.local/lib/` analoguous to `/usr/lib/`,
`~/.local/lib/<arch-id>` analoguous to `/usr/lib/<arch-id>`,
`~/.local/lib32/` and `~/.local/lib64/` analoguous to `/usr/lib32/` and `/usr/lib64/`.

### `~/.local/share/`

Expand Down Expand Up @@ -669,13 +696,14 @@ specific types of files supplied by the vendor.
| Directory | Purpose |
|-------------------------------|---------|
| `/usr/bin/` | Package executables that shall appear in the `$PATH` executable search path, compiled for any of the supported architectures compatible with the operating system. It is not recommended to place internal binaries or binaries that are not commonly invoked from the shell in this directory, such as daemon binaries. As this directory is shared with most other packages of the system, special care should be taken to pick unique names for files placed here, that are unlikely to clash with other package's files. |
| `/usr/lib/<arch-id>/` | Public shared libraries of the package. As above, be careful with using too generic names, and pick unique names for your libraries to place here to avoid name clashes. |
| `/usr/lib/package/` | Private static vendor resources of the package, including private binaries and libraries, or any other kind of read-only vendor data. |
| `/usr/lib/<arch-id>/package/` | Private other vendor resources of the package that are architecture-specific and cannot be shared between architectures. Note that this generally does not include private executables since binaries of a specific architecture may be freely invoked from any other supported system architecture. |
| `$libdir` and other directories described in [Libraries, system programs, and program assets](#libraries-system-programs-and-program-assets) | Public shared libraries of the package. As above, be careful with using too generic names, and pick unique names for your libraries to place here to avoid name clashes. |
| `/usr/lib/<package>/` | Program assets of the package, including shared libraries and plugins,
internal binaries and other programs that are not regularly invoked from a shell, and any other kind of read-only vendor data. |
| `~/.local/lib/<arch-id>/<package>` `~/.local/lib32/<package>` `~/.local/lib64/<package>` | Per-package program assets that are architecture-specific. Note that this generally does not include executables since binaries of a specific architecture may be freely invoked from any other supported system architecture. The specific directory to use should be selected based on the system layout as described in [Libraries, system programs, and program assets](#libraries-system-programs-and-program-assets).|

Additional static vendor files with shared ownership
Additional architecture-independent files
may be installed in the `/usr/share/` hierarchy
to the locations defined by the various relevant specifications.
in the locations defined by the various relevant specifications.

### System package variable files locations

Expand Down
Loading