VBOX Files

What is a .VBOX file?

.VBOX file stands for Oracle VM VirtualBox configuration file of specific virtual machines. The file contains VM configuration but not the guest operating system or its contents. The virtualizer stores it as XML and on desktop it usually located at VM folder path VirtualBox VMs/<name>/<name>.vbox along with disk image, .vdi, .vmdk, .vhd files, snapshots, logs, and often a file named .vbox-prev. Following the inheritance of legacy development process initiated at Innotek and continued by Sun Microsystems, Oracle keeps a unique .vbox file corresponding to a registered VM.

It includes the following properties of XML documents: VM name, the UUIDS, guest OS type, memory size allocation, number of processors, booting method (BIOS/EFI), storage controllers type and configuration, attached disks, adapters configuration, networking, shared folder names, USB filters configuration, sound card configuration and parameters of audio playback, display adapter parameters and snapshot references. Alongside a .vbox file, there is often a backup file - .vbox-prev; it is similar in structure and content with XML but contains the previous saved configuration.

.VBOX file is used by users while dealing with relocating of the virtual machine's folder, Virtualbox recovery after corruption or other problems, version control, testing, etc. For identification of the file format just open it by the text editor and check the xml file including root <VirtualBox> element and a <Machine> entry; the XML document has not binary identifier or magic number. Don't mix it up with disk image because deleting or modifying .vbox affects registration or machine configuration settings, while deleting VM disks affects guest state and content.

How to open a .VBOX file

Technical details

The primary .vbox file is plain XML, typically encoded in UTF-8. No consistent binary header exists. Practically, most .vbox files begin with a common XML declaration: <?xml version="1.0"?> - the only certain signature at the file's start. VirtualBox does not compress the settings, allowing one to open the file with Notepad++, BBEdit, Vim, GNOME Text Editor or any other XML-friendly tool.

Root element is commonly <VirtualBox>. This element contains a version attribute which defines which settings schema the release is based on. Next, inside the root VirtualBox creates one or multiple <Machine> elements, where the data related to machine's name, machine UUID, OSType, snapshotFolder, currentSnapshot, lastStateChange and hardware-version metadata used by VirtualBox when executing this particular machine is saved. Settings schema has evolved from VirtualBox 4.x up to 7.x, and newer versions of VirtualBox could add some elements not supported by the earlier versions of the product. Normally, it is better to use the .vbox file with its own version or with more recent VirtualBox.

Virtual machine storage is defined via XML with controllers, ports, devices, and entries into the media registry pointing to external disks (VDI, VMDK, VHD, ISO) as well as differencing images created by VirtualBox for the snapshots. Snapshots are partially defined within the .vbox file as well as in additional snapshots disk files and metadata stored within VM folder. Copying of the .vbox file without snapshots directory could make your snapshot tree unconsistent.

The file size is rather small, tens to hundreds of kilobytes, as the actual guest filesystem resides in external virtual disk files, which size could range in gigabytes. At the moment there is no widely registered dedicated MIME-type for the setting files; actually application/xml is the type and text/xml is also applied. As XML file contains all references to host's paths, networking mode, shared-folders paths, and device filters, the .vbox file is the definition of the VM and host environment simultaneously.

How to convert .VBOX files

A VirtualBox VM can be migrated using the 'export' command which generates a file with the following syntax: vagrant ssh VBoxManage export "VM Name" -o "VM Name.ova" Alternatively, vagrant ssh VBoxManage export "VM Name" -o "VM Name.ovf" if VMs with unpacked files have to be exported.

If a machine is needed to be imported into VMware Workstation, Fusion, or into vCenter from VirtualBox then one should export the VM to OVA/OVF format in VirtualBox software first and then import in into VMware environment later. As result, the machine usually launches, however, some device configurations specific to VirtualBox might be needed to remove/replace by VMware Tools configuration.

KVM/QEMU requires to convert attached virtual disks using qemu-img and create a new VM machine either in virt-manager/libvirt; the .vbox machine hardware is textual information and can not be used.

Thus the .vbox machine config XML-file is an XML text-file, which is archivable, diffable as a textual entity, but converting of only this XML-file would not move guest files. Conversion involves the attached disks and their migration, as they can be cloned and converted by VBoxManage and qemu-img commands (for disks in formats of VDI, VMDK or other) defined inside XML file. This complicates the process because the snapshots involve conversion of differencing image files and export of whole machine, otherwise it will corrupt VM. It would be also noted that conversion of VM loses Shared folder/USB/NAT forwarding rules/saved states/video acceleration settings/Guest Additions configuration inside machine's files.

Common problems and fixes

VirtualBox gives this error, when the associated .vbox refers to an inexistent UUID of some disk, or of a specific virtual snapshot. It is necessary to restore it either from the backup files or from other sources and attach the restored disk via 'Storage' tab in GUI interface. “Machine UUID already exists” appears when the machine you are importing duplicates the UUID of the already existent machine in your VirtualBox environment. Use GUI clone procedure or manipulate UUIDs in a way specified by using command line tool of VBoxManage.

Error "Failed to open virtual machine located in…" happens due to corrupted XML file, incomplete creation and incorrect permissions settings for the .vbox file. It is possible to compare the damaged and original backup .vbox-prev file and check its XML format correctness prior to repeating attempts to load virtual machine. Errors caused by moving of the machine from a current place occur when paths to related images of disk, DVD/CD or shared directories contain absolute addresses in the .vbox XML format. Change the paths carefully or import the required virtual media back to their right location in 'Storage tab'. The old versions of software might refuse to open settings file which were saved by newer 7.x releases. Upgrade VirtualBox to a proper new version or try to open the .vbox with the last writing release of VirtualBox installed on your computer. Saved machine errors usually appear after upgrading or changing of your hardware, in case your virtual machine had a saved status. Discard the saved state if you do not need the suspended RAM contents. If there are any problems with chain of virtual machine snapshots, recover all related files from the previous backup. In case of manual editing of the XML files, do not open the file while any processes of VirtualBox GUI or VBoxSVC service are run on the computer.

Security considerations

.vbox file is composed of XML configuration data and, as a result, generally does not include any macros, executable scripts or guest file system contents. Accordingly, the file poses relatively small risks to security comparing to, for example, .vdi, .vmdk or .iso files and executable installation packages. Nonetheless, broken XML structure may lead to crashes in parser in Oracle VM VirtualBox or even text editors like Visual Studio Code or Vim - which is why you should keep VirtualBox and your editors updated. The whole VM directory is treated as executable and its XML file could reference some external disks, ISO files as well as boot configurations involving untrusted guest OS execution or disclose usernames of host computer, VM name, location of shared folders, MAC address, forwarding port numbers on NAT service as well as names of iso files.

History and versions

Initially VirtualBox software was a product that was created by company Innotek; and, at first, its public version appeared on 2007 year as cross-platform x86 hypervisor software product. At that time, Sun Microsystems purchased Innotek in 2008 and then in 2010 Oracle company purchased Sun Microsystems. After all, VirtualBox software received its actual name - Oracle VM VirtualBox. About the time of VirtualBox 4.0 release in 2010 machine configuration files were moved to per-machine directory; and, also in that time, the current XML filename .vbox replaced former .xml-like naming for machine configurations. The .vbox and its 4.x generation are marked with significant management changes; the generation includes extension packs, appliances management, and well-known working flow with .vbox and .vbox-prev configurations. VirtualBox versions of 5.x, 6.x generations expanded configuration XML schema of VirtualBox 4.x adding paravirtualization configuration options and also enhanced the configurations of USB controllers and graphics as well as added configurations for VM encryption. VirtualBox 7.0, released in 2022, adds also a new graphical user interface of VirtualBox application as well as new support for guest OS automatic setup, support for TPM functionality, and some new fields for VM configuration in general.

Related formats

VirtualBox employs the native format for disk image file called .VDI instead of .VBOX. .vbox file describes media that have been attached including .vdi, .vmdk, .vhd, or .qcow2; however, disk blocks do not reside in the .vbox file but are referenced through it. As long as the problem is associated solely with saving of settings, sometimes a file in form of .VBOX-PREV could be copied to .vbox in case there is no VirtualBox currently running. As for exchanging the entire appliances and making backups, format OVA is superior because it combines OVF descriptor with all disks packed within tar archive. .OVF descriptor is a representation of XML file used as standard in exports of the appliance; unlike .vbox file, which is less suitable to hypervisors like VMware, OVF is more universally acceptable. As for the hypervisor VMWare, .VMX file is its analogue with different hardware names. .Vagrantfile represents a layer higher in this aspect.