Python API to the VirtualBox VM

One of the important advantages of the VirtualBox virtualization solution is powerful public API allowing to control every aspect of virtual machine configuration and execution. Last month I was working on Python and Java bindings to that API. Those bindings are shipped with VirtualBox 2.0 SDK.

There are two families of API bindings:

SOAP allows to control remote VMs over HTTP, while XPCOM is much more high-performing and exposes certain functionality not available with SOAP. They use very different technologies (SOAP is procedural, while XPCOM is OOP), but as it is ultimately API to the same functionality of the VirtualBox, we kept in bindings original semantics, so other that connection establishment, code could be written in such a way that people may not care what communication channel with VirtualBox instance is used. As an example of how flexible and powerful those API are, I developed extensible Python command line shell to the ViritualBox, usable as simpler CLI alternative to GUI. Same shell code can work with either SOAP or XPCOM connection to the VirtualBox. To start XPCOM version of shell:
  • download VirtualBox 2.0 for your platform (Linux and Solaris Python bindings officially supported)
  • download SDK
  • unpack SDK
  • cd sdk/bindings/xpcom/python/sample
  • export VBOX_PROGRAM_PATH=/opt/VirtualBox-2.0.0/ PYTHONPATH=..:$VBOX_PROGRAM_PATH
  • ./ to start the shell
Currently shell is capable to start/suspend/resume/powerdown VMs, and persistently set any VM variable. You can easily extend shell with your own command, for example let's implement command to show information on hard disk of the machine.
def showvdiCmd(ctx, args):
    mach = argsToMach(ctx,args) 
    if mach == None:
        return 0
    hdd = mach.getHardDisk(ctx['ifaces'].StorageBus.IDE, 0, 0)
    print 'HDD0 info: id=%s desc="%s" size=%dM location=%s' %(,hdd.description,hdd.size,hdd.location)
    return 0

and add following line to commands map:
'vdiinfo':['Show VDI info', showvdiCmd],

Then you can run it like this: vdiinfo Win32 (or however your VM of interest is named). Easy, isn't it? Moreover this command will work not only with XPCOM bindings, but with SOAP too. This example also shows how to access VirtualBox constants in toolkit neutral manner - 'ifaces' field of context contains reflection information useadble to get values of the constant.

Actually, there are other languages bindings to VirtualBox API shipped with SDK, including Java and C++, but I personally find Python easiest for start. You can ask here questions on VirtualBox language bindings (not only Python), and I will try to help.


This is really great.

I'll be very interested to try it out, but I ran into what I think is a missing library on Mac OS 10.5:

Posted by Robert Hopson on September 07, 2008 at 03:06 AM MSD #

Actually problem is that we don't ship 2.5 version yet, but you can build it yourself using VBox OSE. In upcoming releases of VirtualBox may consider to include Python 2.5 support for MacOS.

Posted by Nikolay Igotti on September 08, 2008 at 07:11 AM MSD #

Ah, thanks for the info. I saw mention of 2.5 in bindings/xpcom/python/xpcom/ and thought maybe it was just missing.

Will try building it.

Posted by Robert Hopson on September 08, 2008 at 11:10 AM MSD #

vboxshell is not a shell, it is a command line interface. A \*real\* shell would support functions, if, then, else expressions, loops and other features bash and ksh have. Stop calling this a "shell", it isn't one. The name vboxshell is misleading - not a shell.

Posted by Ralf Schmitt on September 17, 2008 at 11:52 AM MSD #

Let's start flamewars not.
This particular shell, being written in Python can use any Python construct, including loops, functions, or anything else (via eval/exec)- it's just nobody needed it yet. If someone will need it - it may be implemented pretty easily.
Just for your pleasure - may provide eval command in next versions ;).

Posted by Nikolay Igotti on September 17, 2008 at 12:06 PM MSD #

1. A agree with Ralf. A shell is a shell such as the Korn Shell, Bourne Again Shell (aka bash) or zsh. Your demo is a command line interface and not a shell and shall never be called a shell. A shell is easy to use and Python is NOT easy
2. Python is not standardized and the wrong language choice
3. As demo the pyapi is nice but you must go back to the design board and create something new, better


Posted by Nico Krynavoksi on September 24, 2008 at 02:41 PM MSD #

As I already said - I find no interest in useless flamewars - instead enjoy doing new things.
As promised, implemented eval command, allowing full power of Python to be used from the shell (see help eval).

Posted by Nikolay Igotti on September 25, 2008 at 04:23 AM MSD #

functions, if, then, else expressions, loops and other features bash and ksh have make them programming languages, not shells.

Posted by Nicolás on June 07, 2009 at 02:11 AM MSD #

I've been playing with the VBox python API and making some good progress - registering VMs, starting them up, shutting them down, etc. However I'm stuck on how to use the IVirtualBoxCallback interface. I want to use IVirtualBox.registerCallback() to find out when a VM changes state, but I don't understand how to construct the callback argument/object. Any pointers? An example would be much appreciated? Thanks in advance.

Posted by Von on July 05, 2009 at 09:34 PM MSD #

You can look at lastest, shipped with VirtualBox 3.0. It has 'monitorVbox' and 'monitorGuest' commands, using callbacks and waiting for events to happen. It also uses universal wrapper, providing uniform VBox API access from XPCOM, MSCOM and Webservices.

Posted by Nikolay Igotti on July 06, 2009 at 04:37 AM MSD #

Ah, I see has moved to bindings/glue/python/sample in the 3.0 SDK - I missed it. Thanks, that should help.

Posted by Von on July 06, 2009 at 09:44 AM MSD #

How to use Vbox Python API to do some operation in Guest OS (like create process, create file, delete file ). This will be more useful to automate some job in guest OS

Posted by Saravanan Mohankumar on September 19, 2009 at 11:10 AM MSD #

Unfortunately, there's no VBox API to do that yet, so Python bindings cannot help here. You can simulate such a behavior using ssh (with passwordless authentification) and port forwarding. We're considering implementing this feature in next releases.

Posted by nike on September 21, 2009 at 06:02 AM MSD #

I use VirtualBoxSDK-3.0.8-53138, and Python 2.6

I have read the documentation and your reply comment

But I can not understand how I ask the class ISession and call attribute IConsole.

I want using the powerDown - turn off the virtual machine.

The problem is that I do not understand how I can turn to the class ISession.

It would be very thankful and grateful for the help.

Yours sincerely Nikolay Tkachuk

Posted by Nikolay on October 19, 2009 at 07:20 PM MSD #

Use as an example - it has powerDown command.

Posted by Nikolay Igotti on October 20, 2009 at 06:29 AM MSD #

i had a probleme with creating a session to launch a virtual Machine in COM i use the fonction CoCreateInstance and i have this code error 0x80040154 .
i use windows 7 .

and can you please telle me how to create an instance for IVirtualBox from Portable-virtualBox

thanks in advance.

Posted by moncef on January 08, 2010 at 09:03 AM MSK #

HRESULT 0x80040154 means "Class not registered", so maybe you don't have VBox installed, or use wrong CLSID/UUID to get class instance (or use mismatching bitness of COM client and server). Please ask such questions on VirtualBox mailing list:

Posted by guest on January 11, 2010 at 03:49 AM MSK #

I have successfully used VirtualBox API on XP, and I tried it on windows 7 and had COM errors as well. It could be the fact that python extensions for windows has poor support for windows 7, or it could be that my XP is 32bit and my Windows 7 is 64bit.

Posted by guest on January 25, 2010 at 10:20 AM MSK #

hi..I wanted to make a command line interface for virtualbox and i tried controlling the virtual machines using 'pyvb' . it worked...Is there any advantage of using 'pyvb' instead of xpcom? are they the same...???

Posted by ASK on April 16, 2010 at 07:49 AM MSD #

Hi. I want to know if there is a way to create delete IDE controllers on a machine and then attach detach an immutable vdi on this. Thank you

Posted by fanfan on August 12, 2010 at 12:33 PM MSD #

Post a Comment:
  • HTML Syntax: NOT allowed



« April 2014