Synopsis #
FreeBSD can execute many unmodified Linux binaries through a kernel compatibility layer and a Linux userland installed under /compat/linux. This is not a virtual machine or a Linux container. Applications that require Linux namespaces, cgroups, or unsupported kernel interfaces need another approach. For workloads that need a Linux kernel, consider a bhyve virtual machine
.
The compatibility layer is available on x86 32-bit, x86 64-bit, and AArch64 systems. Confirm the application architecture and requirements before installing a userland.
Enable the compatibility service #
Enable the service at boot and start it for the current boot:
# sysrc linux_enable=YES
# service linux start
Confirm that the expected compatibility modules are loaded:
$ kldstat
The exact module list depends on the host architecture and the binary being run.
Install a Linux userland #
Install the Rocky Linux 9 base userland used by current FreeBSD documentation:
# pkg install linux_base-rl9
Files supplied by the Linux userland are installed beneath /compat/linux. Additional Linux packages may be needed for an application’s shared libraries.
Diagnose a binary that does not start #
Kernel missing 64-bit Linux support #
If package installation reports Cannot install package: kernel missing 64-bit Linux support, check the host architecture and the loaded modules with kldstat. Enable the compatibility service
, confirm that the required modules loaded, then retry the installation. If they cannot load, check that the installed kernel and modules support the binary’s architecture.
Other startup failures #
Collect evidence before adding libraries or changing kernel settings:
$ file /path/to/program
$ sysctl compat.linux
For a trusted, dynamically linked Linux executable, ask its Linux loader to report dependencies:
$ env LD_TRACE_LOADED_OBJECTS=1 /path/to/program
Use this only for an executable whose source is trusted. FreeBSD’s native ldd can report a Linux library as missing even when the Linux loader can find it under /compat/linux. Do not install libraries solely from that native ldd result.
Check the following conditions:
- The binary architecture is supported by the host.
- The Linux compatibility service is running after the current boot.
- Required shared libraries exist in the Linux userland rather than only in the FreeBSD base system.
- The application does not require Linux-only kernel facilities such as namespaces or cgroups.
Dependency reporting can fail when the Linux interpreter itself is missing. The binary’s file output and application documentation remain useful in that case.