Vagrant Up with the LXC Provider

The vagrant-lxc plugin allows LXC to be a (custom) provider for Vagrant. This allows Vagrant boxes to be spun up as LXC containers on the host machine.

Depending on your distro and host OS installation add-ons, it may not be enough to just install the plugin as it relies on additional packages for it to work. In this post, I will go through how to set up the vagrant-lxc plugin for a clean installation of Ubuntu Server.


  • Host OS: Ubuntu Server 18.04.3
  • LXC Client/Server Version: 3.0.3
  • Vagrant Version: 2.2.7 (latest version at time of this post)
  • Vagrant Box: debian/jessie64 version 8.7.0 (or any supported box for the LXC provider at

Step 1: Install Required Packages

Starting from a clean installation of the host OS, install the following packages:

$ sudo apt-get install lxc-utils lxc-templates

The Ubuntu Server 18.04.3 distro should already come with LXC installed. If the distro you are using does not have it, install it as well.

Quick explanation on why these packages are needed:

  • lxc-utils –  This package provides the lxc-* tools that the vagrant-lxc plugin uses (e.g. lxc-create)
  • lxc-templates – This package contains the necessary shell scripts to configure and create the LXC container. The templates can be found at /usr/share/lxc/templates

Step 2: Initialize LXD

We need to setup LXD (the defaults should be okay for purposes of testing):

$ lxd init
(press enter for all prompts to accept defaults)

Step 3: Install Vagrant

The Vagrant Installation guide recommends installing directly from the website instead of the distribution package manager, as “typically these packages are missing dependencies or include very outdated versions of Vagrant”.

So let’s get the .deb file from their download page and install with with dpkg:

$ wget (the respective release package for your OS and architecture)

$ sudo dpkg -i (the downloaded .deb file)

$ vagrant version
Installed Version: 2.2.7
Latest Version: 2.2.7

You're running an up-to-date version of Vagrant!

Step 4: Add the vagrant-lxc Plugin

We need this plugin to allow Vagrant to communicate with LXC as a provider. Otherwise, the default supported providers are only hyperv, docker, and virtualbox.

$ vagrant plugin install vagrant-lxc
Installing the 'vagrant-lxc' plugin. This can take a few minutes...
Fetching: vagrant-lxc-1.4.3.gem (100%)
Installed the plugin 'vagrant-lxc (1.4.3)'!

Step 5: Create Vagrantfile

Navigate to your (presumably clean) project directory and create your Vagrantfile. I like to create a minimal (-m flag) Vagrantfile without the comments for simplicity:

$ cd (your-project-directory)
$ vagrant init -m debian/jessie64 --box-version 8.7.0
A `Vagrantfile` has been placed in this directory. You are now
ready to `vagrant up` your first virtual environment! Please read
the comments in the Vagrantfile as well as documentation on
`` for more information on using Vagrant.

Step 6: Vagrant Up

Its time to spin up a LXC container of our box! If its your first time using this box, vagrant will need to spend some time downloading it. Below are some important stdout lines that you would expect to see:

$ vagrant up --provider=lxc
Bringing machine 'default' up with 'lxc' provider...
==> default: Box 'debian/jessie64' could not be found. Attempting to find and install...
==> default: Loading metadata for box 'debian/jessie64'
==> default: Adding box 'debian/jessie64' (v8.7.0) for provider: lxc
==> default: Successfully added box 'debian/jessie64' (v8.7.0) for 'lxc'!
==> default: Importing base box 'debian/jessie64'...
==> default: Checking if box 'debian/jessie64' version '8.7.0' is up to date...
==> default: Setting up mount entries for shared folders...
==> default: Starting container...
==> default: Waiting for machine to boot. This may take a few minutes...
    default: SSH address:
    default: SSH username: vagrant
    default: SSH auth method: private key
    default: Vagrant insecure key detected. Vagrant will automatically replace
    default: this with a newly generated keypair for better security.
    default: Inserting generated public key within guest...
    default: Removing insecure key from the guest if it's present...
    default: Key inserted! Disconnecting and reconnecting using new SSH key...
==> default: Machine booted and ready!

If there are issues with starting up the container, run vagrant up --provider=lxc --debug to see more verbose information about the error.

Verify vagrant up was successful with:

$ vagrant status
Current machine states:
default                   running (lxc)   <-- shows that the LXC

$ vagrant ssh 
vagrant@jessie:~$   <-- this is the vagrant user in the LXC container

Step 7: Vagrant Halt

Due to this issue, halting a Debian (and its derivatives) container freezes indefinitely. According to the issue discussion, other guest containers work fine. So specifically for this Debian container, use the -f flag to force it:

$ vagrant halt -f
==> default: Forcing shutdown of container...

And we are done!

Final Notes:

  • It is important to choose a box and version combination that supports the provider you want. For example, the debian/jessie64 vagrant box page shows that only versions 8.7.0 and 8.6.1 are supported by LXC. Choosing an unsupported version will give you an error message similar to the following:
    • The box you're attempting to add has no available version that
      matches the constraints you requested. Please double-check your
      settings. Also verify that if you specified version constraints,
      that the provider you wish to use is available for these constraints.
      Box: debian/jessie64
      Constraints: 8.8.0
      Available versions: (insert list of supported versions)

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s