How to Install VirtualBox Guest Additions on a VM
Installing VirtualBox Tools — officially called VirtualBox Guest Additions — is one of the first things you should do after setting up a virtual machine. Without them, your VM runs in a kind of basic compatibility mode. With them, you unlock smoother performance, better display handling, shared folders, and seamless mouse integration. Here's exactly how it works and what affects the process for different setups.
What Are VirtualBox Guest Additions?
Guest Additions are a package of drivers and system utilities installed inside the guest operating system (the OS running in your VM). They're separate from VirtualBox itself, which runs on your host machine (your actual physical computer).
Once installed, Guest Additions enable:
- Dynamic screen resizing — the VM display adjusts when you resize the window
- Seamless mouse integration — your cursor moves between host and VM without needing to "capture" it
- Shared clipboard — copy and paste between host and guest
- Shared folders — access host directories from inside the VM
- Improved video performance — hardware-accelerated 2D/3D rendering (where supported)
- Time synchronization — the VM clock stays in sync with your host
Without Guest Additions, you're essentially running a VM with generic VESA display drivers and no integration features.
Before You Start: What You'll Need
- VirtualBox installed on your host machine (Windows, macOS, or Linux)
- A running virtual machine with an OS already installed
- The Guest Additions ISO — this ships with VirtualBox and is usually stored locally on your host
You don't need to download anything separately in most cases. VirtualBox includes the VBoxGuestAdditions.iso file as part of its installation.
How to Install Guest Additions on a Windows VM 🖥️
- Start your virtual machine and let the guest OS fully boot.
- In the VirtualBox menu bar (on your host), click Devices → Insert Guest Additions CD Image…
- This mounts a virtual CD drive inside the Windows VM.
- Open File Explorer inside the VM and navigate to the mounted disc (usually the D: or E: drive).
- Run VBoxWindowsAdditions.exe.
- Follow the installer prompts — accept defaults unless you have a specific reason to change them.
- Restart the VM when prompted.
After rebooting, you'll typically notice the display adjusts automatically, and mouse capture is no longer required.
How to Install Guest Additions on a Linux VM
Linux installations add a small layer of complexity because you may need to install build dependencies first.
Step 1 — Install required packages (inside the Linux VM):
For Debian/Ubuntu-based systems:
sudo apt update sudo apt install build-essential dkms linux-headers-$(uname -r) For Fedora/RHEL-based systems:
sudo dnf install gcc make kernel-devel bzip2 perl Step 2 — Mount the Guest Additions ISO:
In the VirtualBox menu bar, click Devices → Insert Guest Additions CD Image…
Step 3 — Run the installer:
sudo mkdir /mnt/cdrom sudo mount /dev/cdrom /mnt/cdrom cd /mnt/cdrom sudo ./VBoxLinuxAdditions.run Step 4 — Reboot the VM.
If the build dependencies aren't installed beforehand, the installer will partially succeed — it may install some components but fail to compile the kernel modules, which are responsible for display and folder sharing features.
How to Install Guest Additions on a macOS Host with a Linux Guest
The process inside the VM is identical to a standard Linux install. The difference is where VirtualBox stores the ISO on your host. On macOS, VirtualBox typically stores VBoxGuestAdditions.iso at:
/Applications/VirtualBox.app/Contents/MacOS/VBoxGuestAdditions.iso If Devices → Insert Guest Additions CD Image doesn't find it automatically, you can manually attach the ISO via Settings → Storage → Add Optical Drive and point it to that file path.
Common Variables That Affect Installation 🔧
Not every Guest Additions install goes smoothly, and several factors determine the experience:
| Variable | Impact |
|---|---|
| Guest OS version | Older Linux kernels may need older Guest Additions versions |
| VirtualBox version | Guest Additions should match your VirtualBox version closely |
| Kernel headers installed | Linux installs fail silently without them |
| Secure Boot | Can block unsigned kernel modules on some Linux distros |
| VM hardware acceleration settings | Affects whether 3D acceleration actually works post-install |
| User permissions | Must run installer with admin/root rights |
A version mismatch between VirtualBox and the Guest Additions package is a frequent cause of partial functionality — features like shared folders or display resizing may not work even if the installer reported success.
Verifying the Installation
On Windows, check Device Manager for display adapters — you should see VirtualBox Graphics Adapter rather than a generic Microsoft display driver.
On Linux, run:
lsmod | grep vbox You should see modules like vboxguest, vboxsf, and vboxvideo listed. If these aren't loaded, the kernel modules didn't compile correctly and you'll need to revisit the dependency installation step.
When Things Don't Work As Expected
A few scenarios are worth knowing:
- Display still doesn't resize: Check that View → Auto-resize Guest Display is enabled in VirtualBox, and that 3D acceleration isn't conflicting with your VM's video memory setting.
- Shared folders not appearing: The user account inside the Linux VM may need to be added to the
vboxsfgroup:sudo usermod -aG vboxsf yourusername, followed by a logout/login. - Installer fails on Linux: Almost always a missing kernel headers issue. Reinstall dependencies and re-run the installer.
How smoothly any of this lands depends on which guest OS you're running, whether your VirtualBox version is current, and how your VM was originally configured — all things that vary considerably from one setup to the next.