vboxmanage-import

Import a VM from an OVF or OVA file

$ VBoxManage import [path/to/file.ovf]

$ VBoxManage import [path/to/file.ovf] --name [vm_name]

$ VBoxManage import [path/to/file.ovf] --basefolder [path/to/directory]

$ VBoxManage import [path/to/file.ovf] --register

$ VBoxManage import [path/to/file.ovf] --dry-run

$ VBoxManage import [path/to/file.ovf] --ostype=[ostype]

$ VBoxManage import [path/to/file.ovf] --memory=[1]

$ VBoxManage import [path/to/file.ovf] --cpus=[1]

VBoxManage import <ovf-file> [
  --dry-run
  --options <option-list>
  --vsys <number>|all
  --settingsfile <filename>
  --preserve-mac-addresses
  --basefolder <folder>
  --vmname <name>
  --groups <group1>,...
  --cpus <number>
  --memory <MB>
  --vram <MB>
  --accelerate-vram <on|off>
  --eula accept
  (and many other VM configuration options)
]

<ovf-file>
    The path to the OVF descriptor file or the OVA appliance file to be imported.

--dry-run
    Performs a simulation of the import process without actually importing the VM. It prints the proposed settings and any options that can be used to customize the import, useful for generating a --settingsfile or --options list.

--options <option-list>
    Specifies a comma-separated list of options for the import process. These options are typically generated by a --dry-run and allow fine-grained control over the imported VM's settings, such as network adapters or CPU features.

--vsys <number>|all
    Imports a specific virtual system (VM) from a multi-VM OVF package or all of them. Use vboxmanage import <ovf-file> --dry-run to see available vsys numbers if the OVF contains multiple virtual machines.

--settingsfile <filename>
    Imports settings from a specified file. This file can be generated by a --dry-run operation and then modified to customize the import process. It's an alternative to specifying all options on the command line.

--preserve-mac-addresses
    Keeps the original MAC addresses of the network adapters as defined in the OVF/OVA. By default, VirtualBox generates new MAC addresses during import to avoid conflicts.

--basefolder <folder>
    Specifies the absolute path to the folder where the imported VM's files (e.g., .vbox file, virtual disk images) will be stored. If not specified, the default VirtualBox Machines folder is used.

--vmname <name>
    Assigns a specific name to the imported virtual machine. If not provided, VirtualBox uses the name defined in the OVF descriptor.

--groups <group1>,...
    Assigns the imported virtual machine to one or more VirtualBox groups (e.g., 'Servers', 'Development') for better organization within the VirtualBox Manager.

--cpus <number>
    Overrides the number of virtual CPUs specified in the OVF descriptor for the imported VM. This allows adjusting the CPU allocation to match host resources or specific requirements.

--memory <MB>
    Overrides the amount of base memory (RAM) in megabytes specified in the OVF descriptor for the imported VM. Useful for tuning performance based on host memory availability.

--eula accept
    Automatically accepts the End-User License Agreement (EULA) if one is embedded in the OVF/OVA package. This is required for some appliances, and without it, the import process will fail.

--nic<1-N> <type>
    Sets the network attachment type for a specific network adapter (e.g., nat, bridged, hostonly), overriding the OVF settings.

--unit <device-id> --disk <filename>
    Allows specifying a new path for a virtual disk image when importing. This is useful if the disk paths in the OVF are incorrect or you want to relocate them to a specific storage location.

The vboxmanage import command is a crucial utility within Oracle VirtualBox that allows users to import virtual machines from pre-packaged appliance files, typically in the Open Virtualization Format (OVF) or its archive counterpart, OVA (Open Virtual Appliance). OVF is a standardized, open-source, and portable format for packaging and distributing virtual machines, enabling interoperability between various virtualization platforms. An OVA file is essentially a single-file archive containing the OVF descriptor XML file, manifest, certificate, and all associated virtual disk images (VMDK, VDI, etc.).

When you use vboxmanage import, VirtualBox reads the OVF descriptor to understand the virtual machine's configuration, including CPU, RAM, network adapters, disk images, and other hardware settings, then creates a new virtual machine definition and copies the disk images into the specified or default VirtualBox machine folder. This command is indispensable for deploying pre-built virtual appliances, sharing VMs, or migrating them from other virtualization software that supports the OVF standard. It streamlines the process of getting a complex virtual environment up and running with minimal manual configuration.

Disk Space: Ensure sufficient disk space on the host machine for the imported virtual disks, which can be significantly larger than the compressed OVA file.

Hardware Compatibility: The imported VM's hardware configuration (e.g., CPU features, chipsets) might not be fully compatible with your host system, potentially requiring adjustments after import.

Network Configuration: Network settings (e.g., NAT, Bridged, Host-Only) defined in the OVF may not match your host's network environment and often need manual adjustment post-import.

Guest Additions: VirtualBox Guest Additions might not be installed or be outdated in the imported VM, which can affect performance and host-guest integration (e.g., clipboard, drag-and-drop, screen resolution). It's often recommended to update or install them after import.

EULA: Some appliances require explicit acceptance of an End-User License Agreement using the --eula accept option; otherwise, the import will fail.

An OVA file is essentially a TAR archive. You can inspect its contents using `tar -tf ` to see the `.ovf` descriptor file and associated `.vmdk`/`.vdi` disk images. The `.ovf` file itself is an XML document that precisely details the virtual machine's configuration and properties.

While vboxmanage import allows some configuration overrides during the import process, extensive customization (e.g., adding more virtual disks, configuring specific port forwarding rules, changing storage controllers) is often best done after the initial import using the vboxmanage modifyvm command or through the VirtualBox GUI.

Some OVF files include defined properties that can be configured during import. These properties are often presented as 'options' during a --dry-run and can be passed as key-value pairs via the --options parameter, allowing for further customization of the appliance at deployment time.

The Open Virtualization Format (OVF) standard was developed by the Distributed Management Task Force (DMTF) and initially published around 2007. VirtualBox began supporting OVF/OVA import and export capabilities in its early 2.x versions (e.g., VirtualBox 2.2, released in 2009, significantly improved OVF support), making it a long-standing core feature for VM portability and distribution. Its continuous development reflects the growing need for interoperability between virtualization platforms.

vboxmanage export(1), vboxmanage createvm(1), vboxmanage registervm(1), vboxmanage modifyvm(1), vboxmanage list vms(1)