What Guest Additions does and why you need it

Guest Additions is a software package that makes a virtual machine run much better inside VirtualBox. Without it, your mouse moves slowly between the host and guest, your screen resolution is locked at a small size, and copying files between machines is clunky. With it installed, your mouse moves seamlessly, your screen resizes to fit the window, and you can drag files directly between the host and the virtual machine.

Guest Additions also improves performance — your virtual machine uses less CPU and memory to do the same work. The installation itself takes about five minutes and requires a restart of the virtual machine, but the payoff is when ready.

Key Takeaways

  • Guest Additions is a package of drivers and tools that makes your virtual machine respond faster and integrate better with your host computer.
  • You install it by inserting the Guest Additions CD image through VirtualBox's menu, then running the installer inside the virtual machine.
  • The process works the same way on Windows, Linux, and macOS host computers, though the installer inside the guest runs differently depending on whether the guest is Windows or Linux.
  • If the CD does not appear automatically, you can mount it manually by navigating to the VirtualBox installation folder and selecting the ISO file.

Before you start: what you need

You need a virtual machine that is already running and has an operating system installed. The virtual machine does not need to be fully updated, but it should be able to boot and log in. You also need administrator or root access inside the guest — if you are using a standard user account, the installer will ask for a password partway through.

Make sure you have at least 100 MB of free disk space inside the guest. Most modern systems have this by default, but if you are working with a very small virtual machine, check first.

How to insert the Guest Additions CD in VirtualBox

With your virtual machine running and in focus, click the Devices menu at the top of the VirtualBox window. Near the bottom of that menu, you will see Insert Guest Additions CD Image. Click it.

VirtualBox will mount a virtual CD drive and insert the Guest Additions image. Inside the guest, you should see a CD icon appear on the desktop or in the file manager within a few seconds. On Windows guests, a dialog box often pops up automatically asking whether you want to run the installer. On Linux guests, the CD appears but nothing runs automatically — you have to open it yourself.

If nothing appears after 10 seconds, the CD may not have mounted. This sometimes happens if the guest operating system does not have CD autorun enabled, or if VirtualBox cannot find the Guest Additions image file. The next section covers what to do in that case.

If the CD does not appear: mounting it manually

On a Windows guest, open File Explorer and look for a CD drive in the left sidebar or under "This PC". If you see one labeled "VBOXADDITIONS" or similar, double-click it. If you do not see any CD drive at all, right-click on "This PC" and choose "Manage", then go to Device Manager and look for any devices with a warning icon. If you find one, right-click it and choose "Update driver", then "Browse my computer for driver software", then "Let me pick from a list of available drivers on my computer", and select the CD drive from the list. After that, the CD should appear.

On a Linux guest, open a terminal and type sudo mount /dev/cdrom /mnt, then ls /mnt to see if files appear. If you see files like VBoxLinuxAdditions.run, the CD is mounted. If you get an error saying the device does not exist, the CD may not have mounted in VirtualBox. Go back to the Devices menu and try Insert Guest Additions CD Image again.

Running the installer on Windows

If a dialog box appeared when the CD was inserted, click "Run VBoxWindowsAdditions.exe" or "Install". If no dialog appeared, open File Explorer, find the CD drive, and double-click the file named VBoxWindowsAdditions.exe or VBoxWindowsAdditions-amd64.exe (the amd64 version is for 64-bit Windows).

The installer will ask for permission to make changes to your computer — click "Yes". Then it will show a setup wizard. Click "Next" through the screens. You can accept the default installation folder. When the wizard finishes, it will ask whether you want to restart the virtual machine now. Click "Yes" — Guest Additions will not work until you restart.

After the restart, log back in. Your mouse should now move smoothly between the host and guest, and your screen should resize when you resize the VirtualBox window.

Running the installer on Linux

Open a terminal inside the guest. Type cd /media/cdrom (or cd /mnt if you mounted it manually), then ls to see the files. You should see a file named VBoxLinuxAdditions.run.

Type sudo bash VBoxLinuxAdditions.run and press Enter. The installer will ask for your password. Type it and press Enter. The installer will compile some kernel modules — this takes a minute or two and shows a lot of text. When it finishes, type sudo reboot to restart the virtual machine.

After the restart, log back in. Your mouse and screen should now behave the same way as on Windows. If the installer failed with an error about missing kernel headers or build tools, you may need to install those first — on Ubuntu or Debian, type sudo apt install build-essential linux-headers-generic before running the installer again.

Troubleshooting common problems

If the mouse still moves slowly or the screen does not resize after restart, the installation may not have completed. Open a terminal (Windows: Command Prompt, Linux: terminal) and check whether the Guest Additions service is running. On Windows, type sc query VBoxService. On Linux, type systemctl status vboxadd. If either shows "stopped" or "inactive", the service did not start. Restart the virtual machine again.

If you get an error during installation on Linux saying "Unable to find the sources of your current Linux kernel", you need to install the kernel headers package for your distribution before running the installer. The error message usually tells you which package to install. After installing it, run the VBoxLinuxAdditions.run installer again.

If the CD image file is missing from your VirtualBox installation folder, you may have an incomplete or corrupted VirtualBox installation. Uninstall VirtualBox completely, read the latest version from the official VirtualBox website, and install it fresh. The Guest Additions image comes with every VirtualBox installation.

Frequently Asked Questions

Do I need to install Guest Additions on every virtual machine?

You do not have to, but the experience is much better if you do. Without it, your virtual machine will work, but mouse and keyboard input will feel sluggish, you cannot resize the window to fit your screen, and copying files between machines is slow. Most people install it on every virtual machine they plan to use regularly.

Can I uninstall Guest Additions if I change my mind?

Yes. On Windows, go to Control Panel, Programs, Programs and Features, find VirtualBox Guest Additions, and click Uninstall. On Linux, open a terminal and type sudo /opt/VBoxGuestAdditions-*/uninstall.sh. After uninstalling, restart the virtual machine. Your virtual machine will work as before, just without the improvements.

What if I upgrade VirtualBox — do I need to reinstall Guest Additions?

Usually not. Guest Additions from one version of VirtualBox usually works with the next version. However, if you notice problems after upgrading VirtualBox, uninstall Guest Additions inside the guest, then insert the new Guest Additions CD image and install it again. This ensures you have the version that matches your new VirtualBox installation.

Can I install Guest Additions on a virtual machine with no internet connection?

Yes. The Guest Additions CD image is built into VirtualBox and does not require downloading anything. You can insert it and install it on any virtual machine, even if the guest has no network access.