A ruby client library providing an interface to libvirt via FFI.
Switch branches/tags
Nothing to show
Pull request Compare This branch is 1 commit ahead, 131 commits behind mitchellh:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Libvirt Ruby Library

A ruby client library providing the raw interface to libvirt via FFI. This gem provides two things which can be used separately:

  • Ruby Objects - For a more friendly experience, a nice set of Ruby objects above the API which take away a lot of the pain are provided, which is the recommended way of using libvirt with Ruby.
  • Raw API Access - For the power-players out there, you can access the libvirt API directly, with no fluff: Direct access to the C API from Ruby.

Project Status

Unreleased and under development. The project is still under heavy initial development. If you are familiar and interested in any of the following: Ruby, FFI, libvirt, virtualization and you want to get involved, now is the best time!

What is done so far?

  • The FFI function coverage is 100% complete. Some structs and enums are missing, however.
  • Basic [unit] test harness in place. Test early and often.
  • Nice ruby layer starting, not much done in this area. A lot will be done the coming days.


This library will be a gem. First, you need to install libvirt, using your OS's respective package manager. On OS X:

Note: Libvirt installation on OS X is coming along, but is not quite ready yet. Expect an update here soon.

After installing libvirt, install the gem:

gem install libvirt

If you'd like to try the bleeding edge version of libvirt-rb, we try to keep master pretty stable and you're welcome to give it a shot. To do this just clone out the repository and run this from the working directory:

rake install


The usage is still up in the air since the gem is under development. For now, here is some stuff that does work, but doesn't do anything very useful!

require 'libvirt'

cxn = Libvirt::Connection.connect
puts "You are connected to: #{cxn.hypervisor}"
puts "Hypervisor version: #{cxn.hypervisor_version}"
puts "Libvirt version: #{cxn.lib_version}"

Expect more exciting things soon! :)

There are also some examples in the examples/ directory which are worth checking out.


To contribute to the project, fork it and send me pull requests of any changes made. For more information, see the Hacker's Guide and the Contributor's Guide.