# Installation details

As installation of VirtualBox varies depending on your host operating system, we provide installation instructions in four separate chapters for Windows, Mac OS X, Linux and Solaris, respectively.

## Installing on Windows hosts

### Prerequisites

For the various versions of Windows that we support as host operating systems, please refer to .

In addition, Windows Installer 1.1 or higher must be present on your system. This should be the case if you have all recent Windows updates installed.

### Performing the installation

The VirtualBox installation can be started

- either by double-clicking on its executable file (contains both 32- and 64-bit architectures)

- or by entering

      VirtualBox-<version>-<revision>-Win.exe -extract

  on the command line. This will extract both installers into a temporary directory in which you'll then find the usual .MSI files. Then you can do a

      msiexec /i VirtualBox-<version>-<revision>-MultiArch_<x86|amd64>.msi

  to perform the installation.

In either case, this will display the installation welcome dialog and allow you to choose where to install VirtualBox to and which components to install. In addition to the VirtualBox application, the following components are available:

USB support

  This package contains special drivers for your Windows host that VirtualBox requires to fully support USB devices inside your virtual machines.

Networking

  This package contains extra networking drivers for your Windows host that VirtualBox needs to support Bridged Networking (to make your VM's virtual network cards accessible from other machines on your physical network).

Python Support

  This package contains Python scripting support for the VirtualBox API (see ). For this to work, an already working Windows Python installation on the system is required.

  Python version ≥ 2.6 is required. Since VirtualBox 5.1 Python 3 is also supported.

  See, for example, http://www.python.org/download/windows/.

Depending on your Windows configuration, you may see warnings about "unsigned drivers" or similar. Please select "Continue" on these warnings as otherwise VirtualBox might not function correctly after installation.

The installer will create a "VirtualBox" group in the Windows "Start" menu which allows you to launch the application and access its documentation.

With standard settings, VirtualBox will be installed for all users on the local system. In case this is not wanted, you have to invoke the installer by first extracting it by using

    VirtualBox.exe -extract

and then do as follows:

    VirtualBox.exe -msiparams ALLUSERS=2

or

    msiexec /i VirtualBox-<version>-MultiArch_<x86|amd64>.msi ALLUSERS=2

on the extracted .MSI files. This will install VirtualBox only for the current user.

If you do not want to install all features of VirtualBox, you can set the optional `ADDLOCAL` parameter to explicitly name the features to be installed. The following features are available:

VBoxApplication

  Main binaries of VirtualBox.

  This feature must not be absent since it contains the minimum set of files to have working VirtualBox installation.

VBoxUSB

  USB support.

VBoxNetwork

  All networking support; includes the VBoxNetworkFlt and VBoxNetworkAdp features (see below).

VBoxNetworkFlt

  Bridged networking support.

VBoxNetworkAdp

  Host-only networking support.

VBoxPython

  Python support.

  Python version ≥ 2.6 is required. Since VirtualBox 5.1 Python 3 is also supported.

For example, to only install USB support along with the main binaries, do a:

    VirtualBox.exe -msiparams ADDLOCAL=VBoxApplication,VBoxUSB

or

    msiexec /i VirtualBox-<version>-MultiArch_<x86|amd64>.msi ADDLOCAL=VBoxApplication,VBoxUSB

The user is able to choose between NDIS5 and NDIS6 host network filters drivers during the installation. This is realized via a command line parameter `NETWORKTYPE`. The NDIS6 driver is default for Windows Vista and later. For older Windows versions, the installer will automatically select the NDIS5 driver and this cannot be changed. For Windows Vista and later the user can force to install the (legacy) NDIS5 host network filter driver using `NETWORKTYPE=NDIS5`. For example, to install the NDIS5 driver on Windows 7, do

    VirtualBox.exe -msiparams NETWORKTYPE=NDIS5

or

    msiexec /i VirtualBox-<version>-MultiArch_<x86|amd64>.msi NETWORKTYPE=NDIS5

### Uninstallation

As VirtualBox uses the standard Microsoft Windows installer, VirtualBox can be safely uninstalled at any time by choosing the program entry in the "Add/Remove Programs" applet in the Windows Control Panel.

### Unattended installation

Unattended installations can be performed using the standard MSI support.

### Public properties

The following public properties can be specified via MSI API,

    VirtualBox.exe -msiparams NAME=VALUE [...]

or

    msiexec /i VirtualBox-<version>-MultiArch_<x86|amd64>.msi NAME=VALUE [...]

to control additional behavior and/or features of the Windows host installer:

VBOX_INSTALLDESKTOPSHORTCUT

  Specifies whether or not a VirtualBox icon on the desktop should be created.

  Set to `1` to enable, `0` to disable. Default is 1.

VBOX_INSTALLQUICKLAUNCHSHORTCUT

  Specifies whether or not a VirtualBox icon in the Quick Launch Bar should be created.

  Set to `1` to enable, `0` to disable. Default is 1.

VBOX_REGISTERFILEEXTENSIONS

  Specifies whether or not the file extensions .vbox, .vbox-extpack, .ovf, .ova, .vdi, .vmdk, .vhd and .vdd should be associated with VirtualBox. Files of these types then will be opened with VirtualBox.

  Set to `1` to enable, `0` to disable. Default is 1.

VBOX_START

  Specifies whether or not VirtualBox should be started right after successful installation.

  Set to `1` to enable, `0` to disable. Default is 1.

## Installing on Mac OS X hosts

### Performing the installation

For Mac OS X hosts, VirtualBox ships in a disk image (`dmg`) file. Perform the following steps:

1. Double-click on that file to have its contents mounted.

2. A window will open telling you to double click on the `VirtualBox.pkg` installer file displayed in that window.

3. This will start the installer, which will allow you to select where to install VirtualBox to.

After installation, you can find a VirtualBox icon in the "Applications" folder in the Finder.

### Uninstallation

To uninstall VirtualBox, open the disk image (dmg) file again and double-click on the uninstall icon contained therein.

### Unattended installation

To perform a non-interactive installation of VirtualBox you can use the command line version of the installer application.

Mount the disk image (dmg) file as described in the normal installation or use the following command line:

    hdiutil attach /path/to/VirtualBox-xyz.dmg

Then open a terminal session and execute:

    sudo installer -pkg /Volumes/VirtualBox/VirtualBox.pkg -target /Volumes/Macintosh\ HD

## Installing on Linux hosts

### Prerequisites

For the various versions of Linux that we support as host operating systems, please refer to .

You will need to install the following packages on your Linux system before starting the installation (some systems will do this for you automatically when you install VirtualBox):

- Qt 5.3.2 or higher (Qt 5.6.2 or higher recommended);

- SDL 1.2.7 or higher (this graphics library is typically called `libsdl` or similar).

To be precise, these packages are only required if you want to run the VirtualBox graphical user interfaces. In particular, `VirtualBox`, the graphical VirtualBox manager, requires both Qt and SDL; `VBoxSDL`, our simplified GUI, requires only SDL. By contrast, if you only want to run `VBoxHeadless`, neither Qt nor SDL are required.

### The VirtualBox driver modules

In order to run other operating systems in virtual machines alongside your main operating system, VirtualBox needs to integrate very tightly into the system. To do this it installs a "driver" module called `vboxdrv` which does a lot of that work into the system kernel, which is the part of the operating system which controls your processor and physical hardware. Without this kernel module, you can still use the VirtualBox manager to configure virtual machines, but they will not start. It also installs network drivers called `vboxnetflt` and `vboxnetadp` which let virtual machines make more use of your computer's network capabilities and are needed for any virtual machine networking beyond the basic "NAT" mode.

Since distributing driver modules separately from the kernel is not something which Linux supports well, we create the modules on the system where they will be used. This usually means first installing software packages from the distribution which are needed for the "build" process. Normally, these will be the GNU compiler (GCC), GNU Make (make) and packages containing "header files" for your kernel - and making sure that all system updates are installed and that the system is running the most up-to-date kernel included in the distribution. The running kernel and the header files must be updated to matching versions. We will give some instructions for common distributions. For most of them you will want to start by finding the version name of your kernel using the command `uname -r` in a terminal. They assume that you have not changed too much from the original installation, particularly not installed a different kernel type. If you have then you will need to determine yourself what to set up.

- With Debian and Ubuntu-based distributions, you must install the right version of the `linux-headers`, usually whichever of `linux-headers-generic` , `linux-headers-amd64` , `linux-headers-i686` or `linux-headers-i686-pae` best matches the kernel version name; and if it exists the `linux-kbuild` package. Basic Ubuntu releases should have the right packages installed by default.

- On Fedora, Redhat, Oracle Linux and many other RPM-based systems, the kernel version sometimes has a code of letters or a word close to the end of the version name, for example "uek" for the Oracle Enterprise kernel or "default" or "desktop" for the standard SUSE kernels. In this case the package name is `kernel-uek-devel` or equivalent. If there is no such code, it is usually `kernel-devel`.

- On older SUSE and openSUSE Linux, you must install the `kernel-source` and `kernel-syms` packages.

If you suspect that something has gone wrong with module installation, check that your system is set up as described above and try running (as root) the following command:

    rcvboxdrv setup

### Performing the installation

VirtualBox is available in a number of package formats native to various common Linux distributions (see for details). In addition, there is an alternative generic installer (.run) which should work on most Linux distributions. The generic installer packages are built on EL5 systems and thus require reasonable old versions of glibc (version 2.5) and other system libraries.

#### Installing VirtualBox from a Debian/Ubuntu package

First, download the appropriate package for your distribution. The following examples assume that you are installing to a 32-bit Ubuntu Wily system. Use `dpkg` to install the Debian package:

    sudo dpkg -i virtualbox-5.0_@VBOX_VERSION_STRING@_Ubuntu_wily_i386.deb

The installer will also try to build kernel modules suitable for the current running kernel. If the build process is not successful you will be shown a warning and the package will be left unconfigured. Please have a look at `/var/log/vbox-install.log` to find out why the compilation failed. You may have to install the appropriate Linux kernel headers (see ). After correcting any problems, do

    sudo rcvboxdrv setup

This will start a second attempt to build the module.

If a suitable kernel module was found in the package or the module was successfully built, the installation script will attempt to load that module. If this fails, please see for further information.

Once VirtualBox has been successfully installed and configured, you can start it by selecting "VirtualBox" in your start menu or from the command line (see ).

#### Using the alternative generic installer (VirtualBox.run)

The alternative generic installer performs the following steps:

- It unpacks the application files to the target directory,

      /opt/VirtualBox/

  which cannot be changed.

- It builds the VirtualBox kernel modules (`vboxdrv`, `vboxnetflt` and `vboxnetadp`) and installs them.

- It creates `/sbin/rcvboxdrv`, an init script to start the VirtualBox kernel module.

- It creates a new system group called `vboxusers`.

- It creates symbolic links in `/usr/bin` to the a shell script (`/opt/VirtualBox/VBox`) which does some sanity checks and dispatches to the actual executables, `VirtualBox`, `VBoxSDL`, `VBoxVRDP`, `VBoxHeadless` and `VBoxManage`

- It creates `/etc/udev/rules.d/60-vboxdrv.rules`, a description file for udev, if that is present, which makes the USB devices accessible to all users in the `vboxusers` group.

- It writes the installation directory to `/etc/vbox/vbox.cfg`.

The installer must be executed as root with either `install` or `uninstall` as the first parameter.

    sudo ./VirtualBox.run install

Or if you do not have the "sudo" command available, run the following as root instead:

    ./VirtualBox.run install

After that you need to put every user which should be able to access USB devices from VirtualBox guests in the group `vboxusers`, either through the GUI user management tools or by running the following command as root:

    sudo usermod -a -G vboxusers username

The `usermod` command of some older Linux distributions does not support the `-a` option (which adds the user to the given group without affecting membership of other groups). In this case, find out the current group memberships with the `groups` command and add all these groups in a comma-separated list to the command line after the `-G` option, e.g. like this: `usermod -G group1,group2,vboxusers username`.

#### Performing a manual installation

If, for any reason, you cannot use the shell script installer described previously, you can also perform a manual installation. Invoke the installer like this:

    ./VirtualBox.run --keep --noexec

This will unpack all the files needed for installation in the directory `install` under the current directory. The VirtualBox application files are contained in `VirtualBox.tar.bz2` which you can unpack to any directory on your system. For example:

    sudo mkdir /opt/VirtualBox
    sudo tar jxf ./install/VirtualBox.tar.bz2 -C /opt/VirtualBox

or as root:

    mkdir /opt/VirtualBox
    tar jxf ./install/VirtualBox.tar.bz2 -C /opt/VirtualBox

The sources for VirtualBox's kernel module are provided in the `src` directory. To build the module, change to the directory and issue

    make

If everything builds correctly, issue the following command to install the module to the appropriate module directory:

    sudo make install

In case you do not have sudo, switch the user account to root and perform

    make install

The VirtualBox kernel module needs a device node to operate. The above make command will tell you how to create the device node, depending on your Linux system. The procedure is slightly different for a classical Linux setup with a `/dev` directory, a system with the now deprecated `devfs` and a modern Linux system with `udev`.

On certain Linux distributions, you might experience difficulties building the module. You will have to analyze the error messages from the build system to diagnose the cause of the problems. In general, make sure that the correct Linux kernel sources are used for the build process.

Note that the `/dev/vboxdrv` kernel module device node must be owned by root:root and must be read/writable only for the user.

Next, you will have to install the system initialization script for the kernel module:

    cp /opt/VirtualBox/vboxdrv.sh /sbin/rcvboxdrv

(assuming you installed VirtualBox to the `/opt/VirtualBox` directory) and activate the initialization script using the right method for your distribution. You should create VirtualBox's configuration file:

    mkdir /etc/vbox
    echo INSTALL_DIR=/opt/VirtualBox > /etc/vbox/vbox.cfg

and, for convenience, create the following symbolic links:

    ln -sf /opt/VirtualBox/VBox.sh /usr/bin/VirtualBox
    ln -sf /opt/VirtualBox/VBox.sh /usr/bin/VBoxManage
    ln -sf /opt/VirtualBox/VBox.sh /usr/bin/VBoxHeadless
    ln -sf /opt/VirtualBox/VBox.sh /usr/bin/VBoxSDL

#### Updating and uninstalling VirtualBox

Before updating or uninstalling VirtualBox, you must terminate any virtual machines which are currently running and exit the VirtualBox or VBoxSVC applications. To update VirtualBox, simply run the installer of the updated version. To uninstall VirtualBox, invoke the installer like this:

    sudo ./VirtualBox.run uninstall

or as root

    ./VirtualBox.run uninstall

. Starting with version 2.2.2, you can uninstall the .run package by invoking

    /opt/VirtualBox/uninstall.sh

To manually uninstall VirtualBox, simply undo the steps in the manual installation in reverse order.

#### Automatic installation of Debian packages

The Debian packages will request some user feedback when installed for the first time. The debconf system is used to perform this task. To prevent any user interaction during installation, default values can be defined. A file `vboxconf` can contain the following debconf settings:

    virtualbox virtualbox/module-compilation-allowed boolean true
    virtualbox virtualbox/delete-old-modules boolean true

The first line allows compilation of the vboxdrv kernel module if no module was found for the current kernel. The second line allows the package to delete any old vboxdrv kernel modules compiled by previous installations.

These default settings can be applied with

    debconf-set-selections vboxconf

prior to the installation of the VirtualBox Debian package.

In addition there are some common configuration options that can be set prior to the installation, described in .

#### Automatic installation of .rpm packages

The .rpm format does not provide a configuration system comparable to the debconf system. See for how to set some common installation options provided by VirtualBox.

#### Automatic installation options

To configure the installation process of our .deb and .rpm packages, you can create a response file named `/etc/default/virtualbox`. The automatic generation of the udev rule can be prevented by the following setting:

    INSTALL_NO_UDEV=1

The creation of the group vboxusers can be prevented by

    INSTALL_NO_GROUP=1

If the line

    INSTALL_NO_VBOXDRV=1

is specified, the package installer will not try to build the `vboxdrv` kernel module if no module fitting the current kernel was found.

### The vboxusers group

The Linux installers create the system user group `vboxusers` during installation. Any system user who is going to use USB devices from VirtualBox guests must be a member of that group. A user can be made a member of the group `vboxusers` through the GUI user/group management or at the command line with

    sudo usermod -a -G vboxusers username

### Starting VirtualBox on Linux

The easiest way to start a VirtualBox program is by running the program of your choice (`VirtualBox`, `VBoxManage`, `VBoxSDL` or `VBoxHeadless`) from a terminal. These are symbolic links to `VBox.sh` that start the required program for you.

The following detailed instructions should only be of interest if you wish to execute VirtualBox without installing it first. You should start by compiling the `vboxdrv` kernel module (see above) and inserting it into the Linux kernel. VirtualBox consists of a service daemon (`VBoxSVC`) and several application programs. The daemon is automatically started if necessary. All VirtualBox applications will communicate with the daemon through Unix local domain sockets. There can be multiple daemon instances under different user accounts and applications can only communicate with the daemon running under the user account as the application. The local domain socket resides in a subdirectory of your system's directory for temporary files called `.vbox-<username>-ipc`. In case of communication problems or server startup problems, you may try to remove this directory.

All VirtualBox applications (`VirtualBox`, `VBoxSDL`, `VBoxManage` and `VBoxHeadless`) require the VirtualBox directory to be in the library path:

    LD_LIBRARY_PATH=. ./VBoxManage showvminfo "Windows XP"

## Installing on Solaris hosts

For the specific versions of Solaris that we support as host operating systems, please refer to .

If you have a previously installed instance of VirtualBox on your Solaris host, please uninstall it first before installing a new instance. Refer to for uninstall instructions.

### Performing the installation

VirtualBox is available as a standard Solaris package. Download the VirtualBox SunOS package which includes the 64-bit versions of VirtualBox. The installation must be performed as root and from the global zone as the VirtualBox installer loads kernel drivers which cannot be done from non-global zones. To verify which zone you are currently in, execute the `zonename` command. Execute the following commands:

    gunzip -cd VirtualBox-@VBOX_VERSION_STRING@-SunOS.tar.gz | tar xvf -

Starting with VirtualBox 3.1 the VirtualBox kernel package is no longer a separate package and has been integrated into the main package. Install the VirtualBox package using:

    pkgadd -d VirtualBox-@VBOX_VERSION_STRING@-SunOS.pkg

If you are using Solaris Zones, to install VirtualBox only into the current zone and not into any other zone, use `pkgadd -G`. For more information refer to the `pkgadd` manual; see also .

The installer will then prompt you to enter the package you wish to install. Choose "1" or "all" and proceed. Next the installer will ask you if you want to allow the postinstall script to be executed. Choose "y" and proceed as it is essential to execute this script which installs the VirtualBox kernel module. Following this confirmation the installer will install VirtualBox and execute the postinstall setup script.

Once the postinstall script has been executed your installation is now complete. You may now safely delete the uncompressed package and `autoresponse` files from your system. VirtualBox would be installed in `/opt/VirtualBox`.

### The vboxuser group

Starting with VirtualBox 4.1, the installer creates the system user group `vboxuser` during installation for Solaris hosts that support the USB features required by VirtualBox. Any system user who is going to use USB devices from VirtualBox guests must be a member of this group. A user can be made a member of this group through the GUI user/group management or at the command line by executing as root:

    usermod -G vboxuser username

Note that adding an active user to that group will require that user to log out and back in again. This should be done manually after successful installation of the package.

### Starting VirtualBox on Solaris

The easiest way to start a VirtualBox program is by running the program of your choice (`VirtualBox`, `VBoxManage`, `VBoxSDL` or `VBoxHeadless`) from a terminal. These are symbolic links to `VBox.sh` that start the required program for you.

Alternatively, you can directly invoke the required programs from `/opt/VirtualBox`. Using the links provided is easier as you do not have to type the full path.

You can configure some elements of the `VirtualBox` Qt GUI such as fonts and colours by executing `VBoxQtconfig` from the terminal.

### Uninstallation

Uninstallation of VirtualBox on Solaris requires root permissions. To perform the uninstallation, start a root terminal session and execute:

    pkgrm SUNWvbox

After confirmation, this will remove VirtualBox from your system.

If you are uninstalling VirtualBox version 3.0 or lower, you need to remove the VirtualBox kernel interface package, execute:

    pkgrm SUNWvboxkern

### Unattended installation

To perform a non-interactive installation of VirtualBox we have provided a response file named `autoresponse` that the installer will use for responses to inputs rather than ask them from you.

Extract the tar.gz package as described in the normal installation. Then open a root terminal session and execute:

    pkgadd -d VirtualBox-@VBOX_VERSION_STRING@-SunOS-x86 -n -a autoresponse SUNWvbox

To perform a non-interactive uninstallation, open a root terminal session and execute:

    pkgrm -n -a /opt/VirtualBox/autoresponse SUNWvbox

### Configuring a zone for running VirtualBox

Assuming that VirtualBox has already been installed into your zone, you need to give the zone access to VirtualBox's device node. This is done by performing the following steps. Start a root terminal and execute:

    zonecfg -z vboxzone

Replace "vboxzone" with the name of the zone in which you intend to run VirtualBox.

Inside the `zonecfg` prompt add the `device` resource and `match` properties to the zone. Here's how it can be done:

    zonecfg:vboxzone>add device
    zonecfg:vboxzone:device>set match=/dev/vboxdrv
    zonecfg:vboxzone:device>end
    zonecfg:vboxzone>add device
    zonecfg:vboxzone:device>set match=/dev/vboxdrvu
    zonecfg:vboxzone:device>end
    zonecfg:vboxzone>exit

If you are running VirtualBox 2.2.0 or above on Solaris 11 or above, you may add a device for `/dev/vboxusbmon` too, similar to what was shown above. This does not apply to Solaris 10 hosts due to lack of USB support.

Next reboot the zone using `zoneadm` and you should be able to run VirtualBox from within the configured zone.