Managing VirtualBox Virtual Machines through Command Line (with VBoxManage)

This article is part of our Academy Course titled VirtualBox Tutorial: Virtualization Essentials.

In this course, we provide a compilation of VirtualBox tutorials that will help you get started with this virtualization platform. We cover a wide range of topics, from installing the software and performing a basic configuration, to cloning, exporting, importing, and removing virtual machines. With our straightforward tutorials, you will be able to get your own Virtual Machines up and running in minimum time. Check it out here!

Throughout this series we have learned how to create, manage, take / restore snapshots and configure virtual machines via the VirtualBox user interface. By now you should feel comfortable performing these tasks through the UI.

In this article we will explain how to use VBoxManage, the command line alternative, to perform the same operations directly from the shell in your host machine. Among other things, this can prove useful when 1) you need to include your virtual machines in your backup routines (regardless of the operating system you are using), or if you want to perform a management operation through cron in Linux or the Task Scheduler in Windows.

Besides providing the same features of its GUI counterpart, VBoxManage provides others that cannot be accessed (yet) from it. On the other hand, there are tasks that are considerably easier to perform using the GUI, such as creating new virtual machines, and for that reason we will not cover how to do it using the command line.

Introducing VBoxManage

A distinguishing characteristic of VBoxManage is that it needs to be followed by a generic operation or an action to be taken on a virtual machine using its id. We will illustrate this through examples in the next section.

If you are using Linux, VBoxManage was added to your PATH environment variable when you installed it. You can verify by typing

which VBoxManage

If the above command returns the absolute path to the binary file (/usr/bin/VBoxManage in my case), it means the directory where VBoxManage resides (most likely /usr/bin) is in your PATH (no surprise here). I would be surprised if that is not the case.

If you are on Windows, VBoxManage should be located inside the Program Files → Oracle → VirtualBox folder. In order to be able to invoke the commands listed in this guide directly, you will need to use the command prompt (cmd) and either browse to that directory or add it to the current PATH (note that this method applies only to your current Command Prompt session):

set PATH=%PATH%;"C:\Program Files\Oracle\VirtualBox"

For the rest of this guide we will use Linux. If you are using Windows you should not see any major differences, if at all.

Listing virtual machines

To show lists, we will use VBoxManage list. Particularly, we are interested in listing

  • Appliances currently registered with VirtualBox (see Fig. 1), along with their corresponding UUID: VBoxManage list vms
Figure 1: Listing appliances registered with VirtualBox
Figure 1: Listing appliances registered with VirtualBox
  • Virtual machines that are currently running: VBoxManage list runningvms
  • Extension packs that are installed: VBoxManage list extpacks

Fig. 2 shows the expected result of the last two commands, provided that you have at least one virtual machine running and have installed the extension pack as discussed at the beginning of this series:

Figure 2: Listing running virtual machines and the installed extension pack
Figure 2: Listing running virtual machines and the installed extension pack
Keep in mind that you WILL NEED the extension pack in order to use USB drives and devices, among other things. If you arrived at this tutorial without reading the previous guides, you are strongly encouraged to take a look at Virtualization with VirtualBox: Installation and Configuration as soon as possible.

Showing and modifying information and settings of virtual machines

To show all the information available for a particular virtual machine, we will use VBoxManage showvminfo followed by the name of the appliance (as returned by VBoxManage list vms). You will not only be able to see settings as the name, the UUID, and the amount of RAM allocated for this appliance, but also the list (and description) of snapshots taken, the path to the snapshots directory, the location of the log and configuration files, and much more. For example,

VBoxManage showvminfo Ubuntu-SCG

will display all the information about the virtual machine named Ubuntu-SCG. Part of the expected output is shown in Fig. 3:

Figure 3: Displaying information about a virtual machine
Figure 3: Displaying information about a virtual machine

Perhaps you will want to group virtual machines following some sort of criteria. For example, you may want to create a group for a specific project and add some virtual machines to it for easier administration.

Using the following command we will add CentOS7-Node01 and CentOS-Node02 to a group named Cluster. If the group does not exist, it will be created when the first appliance is added to the group. The forward bar (/) before the group name is necessary. Please note that operations that are targeted at modifying settings of virtual machines use the VBoxManage modifyvm:

VBoxManage modifyvm "CentOS7-Node01" --groups "/Cluster"
VBoxManage modifyvm "CentOS7-Node02" --groups "/Cluster"

After you run the above commands, the Cluster group will appear in the user interface with the list of machines that have been assigned to it, as can be seen in Fig. 4:

Figure 4: Grouping virtual machines
Figure 4: Grouping virtual machines

To remove a virtual machine from a group, do:

VBoxManage modifyvm "CentOS7-Node01" --groups ""

Now picture the following scenario. Perhaps you bought some more RAM for your host and can now afford to allocate 2048 MB (instead of the original 1 GB that was allocated during creation). In addition, you just realized that you need to resize the existing virtual disk of Ubuntu-SCG (currently 8 GB) to -let’s say- 15 GB. We can perform both operations from the command line in a snap (note that the virtual machine must be stopped prior to running the following commands):

VBoxManage modifyvm Ubuntu-SCG --memory 2048

To resize a disk, we must first identify it and reference it using either its specific UUID (NOT the appliance’s UUID) or its name. That means we will have to use VBoxManage showvminfo Ubuntu-SCG first to find out this information:

VBoxManage showvminfo Ubuntu-SCG | grep -Ei '(ide|sata)' | grep -i uuid
VBoxManage showhdinfo 6eed1d19-874b-43e2-9278-ef485660731e | grep -i capacity

Fig. 5 shows the values before and after the changes:

Figure 5: Resizing a virtual disk and allocating more memory for an appliance
Figure 5: Resizing a virtual disk and allocating more memory for an appliance

Similarly, to change the name or the device the first network interface is attached to (bridged to eth0 in this case), you can do

VBoxManage modifyvm Ubuntu-SCG --name "Ubuntu-SCG-New"

and (use the new name here if you ran the above command previously):

VBoxManage modifyvm "Ubuntu-SCG-New" --nic1 bridged --bridgeadapter1 eth0

Let’s now see how we can export virtual machines using the command line.

Exporting and importing appliances

In the case you do your backups using some sort of shell script, VBoxManage export (followed by the virtual machine name, can help you get the job done. The following command will export the CentOS7 appliance to ~/VMexports/CentOS7.ova:

VBoxManage export CentOS7 --output ~/VMexports/CentOS7.ova

To import it (not surprisingly), we will use VBoxManage import:

VBoxManage import ~/VMexports/CentOS7.ova

You can use the -n (--dry-run) option with VBoxManage to simulate the import process. The machine will not be imported, just a simulation will be performed.

Starting and stopping virtual machines

Suppose you need to start a virtual machine at a give time. To accomplish this, you can create a shell script that runs -through cron- the following command:

VBoxManage startvm CentOS7 --type headless

The --type headless option ensures no GUI is brought up.

To force stop the machine, simply do:

VBoxManage controlvm CentOS7 poweroff

Note that you should resort to the above alternative in case where you cannot access the appliance by any other method (SSH, RDP, etc). Otherwise, you run the risk of damaging it.


In this article we have explained how to use VBoxManage, VirtualBox’s command line alternative for managing appliances. Since this topic would deserve a series of its own, we only covered the most frequently used options. You can refer to Chapter 8 of the VirtualBox documentation guide for a complete list of options and available command line operations.

Gabriel Canepa

Gabriel Canepa is a Linux Foundation Certified System Administrator (LFCS-1500-0576-0100) and web developer from Villa Mercedes, San Luis, Argentina. He works for a worldwide leading consumer product company and takes great pleasure in using FOSS tools to increase productivity in all areas of his daily work. When he's not typing commands or writing code or articles, he enjoys telling bedtime stories with his wife to his two little daughters and playing with them, the great pleasure of his life.
Notify of

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Inline Feedbacks
View all comments
Back to top button