Python API on top of VirtualBox Python SDK API
Switch branches/tags
Nothing to show
Failed to load latest commit information.
pyVBox Fixed VirtualMachine.getHardDrives(). Closes #7. Apr 15, 2012
utils vm command: Handle error in displaying a VM and keep going. Apr 15, 2012
README.markdown Implemented use of setuptools. Jan 18, 2010



This is pyVBOX, a shim layer above the VirtualBox Python API.

Why? Becuase the VirtualBox Python API is somewhat complex and I got tried of trying to remember all the details of its use. Plus it changes from release to release and this gives me an abstraction layer to hide those changes. The software also includes a script, utils/, that provides the ability to manipulate VMs (like VBoxMange).

This code is written to the 4.1 version of VirtualBox (4.1.12 specifically). I have not tried it against any other version.

This software is independently created from VirtualBox and Oracle. No endorsement by Oracle or the VirtualBox authors is implied.

Use at your own risk. No support guarenteed, but I'm happy to receive bug reports or suggestions (open an issue please).

This code is released under the Apache License, Version 2.0. I ask you send me email ( if you add any enhancements or just find it useful (open an issue to report a bug please).

Kudos to Nikolay Igotti and the example that comes with the Virtualbox SDK.

The home page for this code is


My goal is to provide functionality in the pyVBox library, exposed through the script, to do the following:

  • Given a VM on a USB drive, register it, boot it and then when it completes unregister it, all with one command. DONE: the 'boot' command provides this.

  • Allow me to backup a running VM. DONE: the 'backup' command will suspend a VM, if needed, and make backup copies of all its attached hard drives. I'd still like to play around with using snapshops so that the VM doesn't have to be suspended.

  • Allow me to make a copy of a VM with one command. I make what I call 'base VMs' for different OS'es and then when I want a VM for a specific application I copy the base VM and customize the copy. You can do this with a combination of VBoxManage and the VirutalBox GUI, but it's a multi-step process. DONE: the 'clone' command will clone a VM, not perfectly, but well enough the clone will boot.

One I accomplish the above, I'll probably release 1.0 and then decide what comes next.

Installing vboxapi

pyVBox relies on the vboxapi that comes with the VirtualBox SDK from Oracle. You must install it first before trying to use pyVBox.

  1. Download and install VirtualBox from the VirtualBox downloads page.

  2. Download the VirtualBox SDK from the VirtualBox downloads page.

  3. Unzip the SDK somewhere

  4. cd sdk/installer

  5. Set your VBOX_INSTALL_PATH via:

     # VBOXMANAGE_PATH=`which VBoxManage`
     # export VBOX_INSTALL_PATH=`basename $VBOXMANAGE_PATH`
  6. Install:

     # python install

Setting up your environment

(TODO: Update this to use

You will need to include two paths in your PYTHONPATH environent variable:

  1. The directory containing the pyVBox module directory. I.e. the directory in which you found this README.

  2. The bindings/xpcom/python/ directory in the VirtualBox SDK distribution.

For example (assuming your current directory is the one where you found this README file, and you unpacked the VirtualBox SDK to /usr/local/virtualbox-sdk):

setenv PYTHONPATH `pwd`:/usr/local/virtualbox-sdk/bindings/xpcom/python/


Basically I'm creating wrappers around the VirtualBox Python API that adhere to the OO interface it provides, with a few tweaks:

  • Provide reasonable defaults for the VirtualBox methods where it makes sense. Where 'reasonable' of course means what I consider to be reasonable.

  • Provider for some higher-level functionality. E.g. for a VirtualMachine I provide a eject() method that does whatever is needed to unregister the VM.

  • In order to make things more intuitive, I move methods to the class they are associated with. For example, to find a VM you use VirtualMachine.find() instead of VirtualBox.findMachine(). Again 'intuitive' is what I consider to be intuitive.

For all the classes you should still be able to access any of the provider VirtualBox methods, attributes, etc. (I.e. I'm subclassing them, or the equivalent there of).


There is a test suite in test/ which you can invoke with:

    python test

Other issues

Python Version on the Mac

On Mac, you need to use python that came with OS or you will get a 'Cannot find VBoxPython module' error. See this thread.