3.1. Where Oracle VM VirtualBox Stores its Files

In Oracle VM VirtualBox, a virtual machine and its settings are described in a virtual machine settings file in XML format. In addition, most virtual machines have one or more virtual hard disks, which are typically represented by disk images, such as those in VDI format. Where all these files are stored depends on which version of Oracle VM VirtualBox created the machine.

3.1.1. Machines Created by Oracle VM VirtualBox Version 4.0 or Later

By default, each virtual machine has one directory on your host computer where all the files of that machine are stored: the XML settings file, with a .vbox file extension, and its disk images.

By default, this machine folder is placed in a common folder called VirtualBox VMs, which Oracle VM VirtualBox creates in the current system user's home directory. The location of this home directory depends on the conventions of the host operating system, as follows:

  • On Windows, this is the location returned by the SHGetFolderPath function of the Windows system library Shell32.dll, asking for the user profile. On very old Windows versions which do not have this function or where it unexpectedly returns an error, there is a fallback based on environment variables. First, %USERPROFILE% is checked. If it does not exist then an attempt with %HOMEDRIVE%%HOMEPATH% is made. A typical location is C:\Users\username.

  • On Linux, Mac OS X, and Oracle Solaris, this is generally taken from the environment variable $HOME, except for the user root where it is taken from the account database. This is a workaround for the frequent trouble caused by users using Oracle VM VirtualBox in combination with the tool sudo which by default does not reset the environment variable $HOME. A typical location on Linux and Oracle Solaris is /home/username and on Mac OS X /Users/username.

For simplicity, we will abbreviate the location of the home directory as $HOME. Using that convention, the common folder for all virtual machines is $HOME/VirtualBox VMs.

As an example, when you create a virtual machine called "Example VM", Oracle VM VirtualBox creates the following:

  • A machine folder $HOME/VirtualBox VMs/Example VM/

  • In the machine folder, a settings file: Example VM.vbox

  • In the machine folder, a virtual disk image: Example VM.vdi.

This is the default layout if you use the Create New Virtual Machine wizard described in Creating Your First Virtual Machine. Once you start working with the VM, additional files are added. Log files are in a subfolder called Logs, and if you have taken snapshots, they are in a Snapshots subfolder. For each VM, you can change the location of its snapshots folder in the VM settings.

You can change the default machine folder by selecting Preferences from the File menu in the Oracle VM VirtualBox main window. Then, in the displayed window, click on the General tab. Alternatively, use VBoxManage setproperty machinefolder. See VBoxManage setproperty.

3.1.2. Machines Created by Oracle VM VirtualBox Versions Before 4.0

If you have upgraded to Oracle VM VirtualBox 4.0 from an earlier version of Oracle VM VirtualBox, you probably have settings files and disks in the earlier file system layout.

Before version 4.0, Oracle VM VirtualBox separated the machine settings files from virtual disk images. The machine settings files had an .xml file extension and resided in a folder called Machines under the global Oracle VM VirtualBox configuration directory. See Section 3.1.3, “Global Configuration Data”. On Linux, for example, this was the hidden directory $HOME/.VirtualBox/Machines. The default hard disks folder was called HardDisks and was also located in the .VirtualBox folder. Both locations could be changed by the user in the global preferences. The concept of a default hard disk folder was abandoned with Oracle VM VirtualBox 4.0, since disk images now reside in each machine's folder by default.

The old layout had the following severe disadvantages:

  • It was very difficult to move a virtual machine from one host to another because the files involved did not reside in the same folder. In addition, the virtual media of all machines were registered with a global registry in the central Oracle VM VirtualBox settings file, $HOME/.VirtualBox/VirtualBox.xml.

    To move a machine to another host, it was therefore not enough to move the XML settings file and the disk images, which were in different locations, but the hard disk entries from the global media registry XML had to be meticulously copied as well. This was close to impossible if the machine had snapshots and therefore differencing images.

  • Storing virtual disk images, which can grow very large, under the hidden .VirtualBox directory, at least on Linux and Oracle Solaris hosts, made many users wonder where their disk space had gone.

Whereas new VMs created with Oracle VM VirtualBox 4.0 or later will conform to the new layout, for maximum compatibility, old VMs are not converted to the new layout. Otherwise machine settings would be irrevocably broken if a user downgraded from 4.0 back to an older version of Oracle VM VirtualBox.

3.1.3. Global Configuration Data

In addition to the files of the virtual machines, Oracle VM VirtualBox maintains global configuration data in the following directory:

  • Linux and Oracle Solaris: $HOME/.config/VirtualBox.

    $HOME/.VirtualBox is used if it exists, for compatibility with legacy versions before Oracle VM VirtualBox 4.3.

  • Windows: $HOME/.VirtualBox.

  • Mac OS X: $HOME/Library/VirtualBox.

Oracle VM VirtualBox creates this configuration directory automatically, if necessary. Optionally, you can specify an alternate configuration directory by setting the VBOX_USER_HOME environment variable, or additionally on Linux or Oracle Solaris by using the standard XDG_CONFIG_HOME variable. Since the global VirtualBox.xml settings file points to all other configuration files, this enables switching between several Oracle VM VirtualBox configurations.

Most importantly, in this directory, Oracle VM VirtualBox stores its global settings file, another XML file called VirtualBox.xml. This includes global configuration options and the list of registered virtual machines with pointers to their XML settings files. Neither the location of this file nor its directory has changed with Oracle VM VirtualBox 4.0.

Before Oracle VM VirtualBox 4.0, all virtual media, such as disk image files, were also contained in a global registry in this settings file. For compatibility, this media registry still exists if you upgrade Oracle VM VirtualBox and there are media from machines which were created with a version before 4.0. If you have no such machines, then there will be no global media registry. With Oracle VM VirtualBox 4.0, each machine XML file has its own media registry.

Also before Oracle VM VirtualBox 4.0, the default Machines folder and the default HardDisks folder resided under the Oracle VM VirtualBox configuration directory, such as $HOME/.VirtualBox/Machines on Linux. If you are upgrading from an Oracle VM VirtualBox version before 4.0, files in these directories are not automatically moved in order not to break backwards compatibility.

3.1.4. Summary of 4.0 Configuration Changes

The following table gives a brief overview of the configuration changes between legacy versions and version 4.0 or later.

Table 3.1 Configuration Changes in Version 4.0 or Above

Setting

Before 4.0

4.0 or above

Default machines folder

$HOME/.VirtualBox/Machines

$HOME/VirtualBox VMs

Default disk image location

$HOME/.VirtualBox/HardDisks

In each machine's folder

Machine settings file extension

.xml

.vbox

Media registry

Global VirtualBox.xml file

Each machine settings file

Media registration

Explicit open/close required

Automatic on attach


3.1.5. Oracle VM VirtualBox XML Files

Oracle VM VirtualBox uses XML for both the machine settings files and the global configuration file, VirtualBox.xml.

All Oracle VM VirtualBox XML files are versioned. When a new settings file is created, for example because a new virtual machine is created, Oracle VM VirtualBox automatically uses the settings format of the current Oracle VM VirtualBox version. These files may not be readable if you downgrade to an earlier version of Oracle VM VirtualBox. However, when Oracle VM VirtualBox encounters a settings file from an earlier version, such as after upgrading Oracle VM VirtualBox, it attempts to preserve the settings format as much as possible. It will only silently upgrade the settings format if the current settings cannot be expressed in the old format, for example because you enabled a feature that was not present in an earlier version of Oracle VM VirtualBox.

As an example, before Oracle VM VirtualBox 3.1, it was only possible to enable or disable a single DVD drive in a virtual machine. If it was enabled, then it would always be visible as the secondary master of the IDE controller. With Oracle VM VirtualBox 3.1, DVD drives can be attached to arbitrary slots of arbitrary controllers, so they could be the secondary slave of an IDE controller or in a SATA slot. If you have a machine settings file from an earlier version and upgrade Oracle VM VirtualBox to 3.1 and then move the DVD drive from its default position, this cannot be expressed in the old settings format; the XML machine file would get written in the new format, and a backup file of the old format would be kept.

In such cases, Oracle VM VirtualBox backs up the old settings file in the virtual machine's configuration directory. If you need to go back to the earlier version of Oracle VM VirtualBox, then you will need to manually copy these backup files back.

We intentionally do not document the specifications of the Oracle VM VirtualBox XML files, as we must reserve the right to modify them in the future. We therefore strongly suggest that you do not edit these files manually. Oracle VM VirtualBox provides complete access to its configuration data through its the VBoxManage command line tool, see VBoxManage and its API, see Chapter 4, Oracle VM VirtualBox Programming Interfaces.