This version of the doc is no longer supported. Please check out the stable docs for the latest in Juju.

Using LXD as a cloud

LXD provides a fast, powerful, self-contained and largely configuration-free way to experiment with Juju. Using lightweight LXC containers as instances, even a moderately powerful laptop can create useful models, or serve as a development platform for your own charms.


Juju's support for LXD currently works only with Ubuntu 16.04 (Xenial).

Install LXD:

sudo apt install lxd
newgrp lxd

Alternate backing file-system

LXD can optionally use an alternative file-system for containers. We recommend using ZFS for the best experience. To use ZFS with LXD enter these commands:

sudo apt install zfsutils-linux
sudo mkdir /var/lib/zfs
sudo truncate -s 32G /var/lib/zfs/lxd.img
sudo zpool create lxd /var/lib/zfs/lxd.img
sudo lxd init --auto --storage-backend zfs --storage-pool lxd

Above we allocated 32GB of space to a sparse file. Consider using a fast block device if available.

Create a controller (bootstrap)

It is time to create the controller for LXD. Below, we call it 'lxd-xenial':

juju bootstrap lxd lxd-test

This will result in the controller being visible with the LXC client:

lxc list
|     NAME      |  STATE  |         IPV4          | IPV6 |    TYPE    | SNAPSHOTS |
| juju-669cb0-0 | RUNNING | (eth0) |      | PERSISTENT | 0         |

See more examples of Creating a controller.

Next steps

A controller is created with two models - the 'controller' model which should be reserved for Juju's operations, and a model named 'default' for deploying user workloads.

Additional information about LXD

LXD and images

LXD is image based: all LXD containers come from images and any LXD daemon instance (also called a "remote") can serve images. When LXD is installed a locally-running remote is provided (Unix domain socket) and the client is configured to talk to it (named 'local'). The client is also configured to talk to several other, non-local, ones (named 'ubuntu', 'ubuntu-daily', and 'images').

An image is identified by its fingerprint (SHA-256 hash), and can be tagged with multiple aliases. Juju looks for images with aliases in the format ubuntu-<codename>, for instance 'ubuntu-trusty' or 'ubuntu-xenial'.

For any image-related command, an image is specified by its alias or by its fingerprint. Both are shown in image lists. An image's filename is its full fingerprint while an image list displays its partial fingerprint. Either type of fingerprint can be used to refer to images.

Juju pulls official cloud images from the 'ubuntu' remote ( and creates the necessary alias. Any subsequent requests will be satisfied by the LXD cache (/var/lib/lxd/images). Cached images can be seen with lxc image list:

lxc image list after importing

Image cache expiration and image synchronization mechanisms are built-in.


LXD itself logs to /var/log/lxd/lxd.log and Juju machines created via the LXD local provider log to /var/log/lxd/juju-{uuid}-machine-{#}. However, the standard way to view logs is with the juju debug-log command. See Viewing logs for more details.


Although not Juju-related, see lxc --help for more on LXD client usage and lxd --help for assistance with the daemon. See upstream documentation for how to configure the lxd daemon and containers .

For additional configuration of LXD controllers, please see the Controllers documentation.