Oracle VirtualBox Guest Additions are a set of guest-side drivers and system services that improve integration between a virtual machine and its host. A GNU/Linux VM can boot and run without them, but several desktop and file-sharing features may be unavailable or less convenient.
Depending on the guest desktop and VM settings, Guest Additions enable automatic display resizing, improved pointer integration, a shared clipboard, drag and drop, shared folders, and other host-to-guest communication features.
This guide covers installing the official VirtualBox 7.2.20 Guest Additions inside a GNU/Linux VM and verifying that they actually work. The procedure is straightforward when the running kernel and the installed kernel development files match; mismatched headers are a frequent source of installation problems.
Version reference: Oracle VirtualBox 7.2.20 (September 2026). Oracle publishes VBoxGuestAdditions_7.2.20.iso alongside the corresponding VirtualBox release. For best results, keep host VirtualBox and guest additions on matching versions when possible.
Official files: VirtualBox downloads and VBoxGuestAdditions_7.2.20.iso.
If your Linux guest is not ready yet, start with our guide to creating a GNU/Linux virtual machine in VirtualBox.
Before you begin: take a snapshot
If this VM contains important data or already has an older Guest Additions installation, take a snapshot before changing kernel modules and guest services. This is particularly useful when replacing guest integration packages supplied by a Linux distribution.
A snapshot is not a substitute for a full backup, but it provides a convenient rollback point for a test VM. If you are new to virtualization, prepare the GNU/Linux guest and confirm that it boots correctly before proceeding.
What gets installed?
Guest Additions are not one application. They combine kernel drivers and userspace processes to provide capabilities such as:
- Integrated mouse-pointer behavior.
- Automatic screen resizing and display integration.
- Clipboard sharing between the host and the VM.
- Drag and drop where the guest desktop supports it.
- Host-accessible shared folders.
- Time synchronization and guest-host communication services.
- Guest information that VirtualBox can report to the host.
These features can be configured separately. For example, a lab with strict isolation requirements may deliberately leave clipboard synchronization and drag and drop disabled.
Check your running Linux kernel
Guest Additions may need to compile modules against the kernel currently running inside the VM. Find that version first:
uname -rInstalled headers and development packages must match this kernel. A common failure occurs after a distribution upgrade: the system downloads a newer kernel and headers, but the VM is still booted into the previous kernel. The Guest Additions installer then cannot find a consistent build environment.
If you have just upgraded your kernel, reboot and recheck uname -r before trying again.
Prepare Debian, Ubuntu, and derivatives
Install a compiler toolchain, Perl, and headers for the running kernel:
sudo apt update
sudo apt install build-essential perl linux-headers-$(uname -r)If linux-headers-$(uname -r) cannot be found, do not try random packages. Check for a pending reboot, a custom kernel, or a kernel whose development files are provided by a different repository.
Prepare Fedora, RHEL, Rocky Linux, and AlmaLinux
On RPM-based distributions, package names differ. A common starting point is:
sudo dnf install gcc make perl kernel-devel kernel-headersMake sure the installed kernel-devel package corresponds to the kernel returned by uname -r. Oracle Linux systems using the Unbreakable Enterprise Kernel (UEK) may need kernel-uek-devel instead. Always check the distribution’s documentation.
Mount VBoxGuestAdditions.iso
With the VM powered on, open the VirtualBox menu and select Devices → Insert Guest Additions CD Image. VirtualBox attaches the VBoxGuestAdditions.iso image as a virtual optical drive.
The ISO is usually installed along with VirtualBox on the host. On many systems, the menu item locates it automatically, so you do not need to download it separately.
Most desktop environments mount the image automatically. If yours does not, inspect available block devices:
lsblkFind the optical device and mount it manually in a temporary directory if necessary. Confirm you are running commands inside the guest, not on the host.
Run the Guest Additions installer
Open a terminal in the directory where the ISO is mounted and run:
sudo sh ./VBoxLinuxAdditions.runThe installer checks the guest environment, builds any required kernel modules, and installs the corresponding services. Read the output carefully: an installer script can exit while reporting that one or more modules could not be built.
If it reports missing headers, compiler errors, kernel-module failures, or a version mismatch, address that root cause before trying again.
Verify kernel modules and guest services
VirtualBox provides dedicated commands to check the Guest Additions installation. For the kernel drivers:
sudo rcvboxadd status-kernelFor the userspace guest service:
sudo rcvboxadd status-userYou can also inspect loaded modules:
lsmod | grep -i vboxIf compilation initially failed and you have now installed the correct build dependencies, Oracle documents the following setup command:
sudo rcvboxadd setupThis rebuilds and configures the relevant modules. Review its output rather than assuming success.
Confirm the installed Guest Additions version
Check what the guest installation reports:
VBoxControl --version
modinfo vboxguest | grep -E "version|vermagic"The exact available commands can depend on installation method and distribution packages. If the host has been upgraded but the VM has a much older set of Guest Additions, consider updating the guest to match.
UEFI Secure Boot and signed kernel modules
A GNU/Linux guest using UEFI Secure Boot may refuse to load an unsigned third-party module. If vboxguest, vboxsf, or related drivers do not load after an apparently successful installation, inspect kernel messages and module-signing requirements before disabling Secure Boot.
mokutil --sb-state
dmesg | grep -i -E "vbox|secure|module"Some distributions have a Module Owner Key (MOK) signing workflow. Follow the distribution-specific procedure if you need to sign or enroll externally built modules.
Do you need to reboot?
Some Guest Additions changes can take effect without rebooting, but a restart is a sensible choice after the initial installation to ensure kernel modules, services, and desktop-session processes start in a clean state:
sudo rebootAfter rebooting, resize the VirtualBox window. Automatic adjustment of the desktop resolution and proper mouse integration are useful first checks, although their behavior depends on the graphics controller and desktop session.
Shared clipboard and drag and drop
Installing Guest Additions does not automatically enable every host-guest sharing feature. In VirtualBox’s Devices menu, configure clipboard sharing as disabled, host-to-guest, guest-to-host, or bidirectional as appropriate.
The shared clipboard creates another path for information to cross the host/guest boundary. Keep it off in sensitive or isolated labs unless required.
Drag-and-drop support can vary by desktop environment, file manager, and X11 versus Wayland session. If it does not work, check the installed drivers and services before concluding that the entire Guest Additions installation is broken.
Shared folders and the vboxsf group
Auto-mounted VirtualBox shared folders are commonly exposed to the GNU/Linux guest under /media with an sf_ prefix. A shared folder named data, for example, might appear at:
/media/sf_dataOracle generally limits access to automatically mounted shared folders to root and members of the vboxsf group. To add your user to that group:
sudo usermod -aG vboxsf "$USER"Log out completely and sign in again so the group membership takes effect. Then check:
groupsRemember that shared folders weaken isolation by design; do not mount sensitive host paths inside untrusted guest systems.
Oracle Guest Additions versus distribution packages
Some distributions include their own Guest Additions packages, which are convenient because they receive updates through the system package manager. Those packages may not exactly match the version installed on the host.
Oracle recommends matching the host and guest versions when practical. Avoid combining the distribution-provided packages with a manually installed Guest Additions ISO without understanding which drivers and services are active.
If you choose distribution packages, follow the distribution’s integration documentation. If you need a specific Oracle VirtualBox release, use the corresponding ISO and verify the resulting installation.
Guest Additions stopped working after a kernel update
Kernel updates can leave Guest Additions modules missing or incompatible until they are rebuilt for the new kernel.
First check:
uname -r
sudo rcvboxadd status-kernelInstall any missing matching headers, then rebuild:
sudo rcvboxadd setupIf the issue remains, inspect the installer log and system journal rather than repeatedly reinstalling unrelated packages.
Updating Guest Additions
Guest Additions can sometimes continue working across host updates because Oracle maintains compatibility in their communication interfaces. Nevertheless, matching versions generally makes troubleshooting easier.
To update, attach the new VBoxGuestAdditions.iso, repeat the installation, and verify kernel modules and guest services again.
Final verification checklist
rcvboxadd status-kernelreports no unexpected error.- The guest service is running.
- The display resizes with the VM window where supported.
- Mouse-pointer integration works correctly.
- Shared clipboard and folders work if you chose to enable them.
- Guest Additions versions are aligned with your host VirtualBox release.
VirtualBox series
Explore other VirtualBox guides in our virtualization series.
