How to use remote images

Images are downloaded through image registries. The lxc CLI command is pre-configured with several built-in image registries that provide the most common public image sources.

Note

In the CLI, remotes are used to connect to other LXD servers (see How to add remote servers), not to source images. To add a new image source, create an image registry instead of adding a remote. For backwards compatibility, older CLI clients that still reference an image through a remote keep working as long as a matching image registry exists on the server.

  • If you are using the API, you can interact with different LXD servers by using their exposed API addresses. See Authenticate with the LXD server for instructions on how to authenticate with the servers.

    How to manage images describes how to interact with images on any LXD server through the API.

  • The UI is pre-configured with several image sources, but does not currently support adding other sources or managing remote images.

    You can see the available images (and which source they come from) when you select the base image for a new instance.

List available images

To list the images provided by an image registry, use the --registry flag:

lxc image list --registry <registry_name>

To see which image registries are available, run lxc image registry list. See How to manage image registries for more information.

You can filter the results. See Filter available images for instructions.

Add an image source

To make a new image source available for download, create an image registry.

  • For a SimpleStreams image server, create a registry with the server’s url.

  • For another LXD server, create a registry that references a cluster link.

Add a remote LXD server

You can add a LXD server as a remote to manage it over the network (for example, to copy images between servers).

To see all configured remote servers, enter the following command:

lxc remote list

To add a LXD server as a remote, enter the following command:

lxc remote add <remote_name> <IP|FQDN|URL|token> [flags]

Some authentication methods require specific flags (for example, use lxc remote add <remote_name> <IP|FQDN|URL> --auth-type=oidc for OIDC authentication). See Authenticate with the LXD server and Remote API authentication for more information.

For example, enter the following command to add a remote through an IP address:

lxc remote add my-remote 192.0.2.10

You are prompted to confirm the remote server fingerprint and then asked for the token.

Reference an image

To reference an image, specify its image registry and its alias or fingerprint, separated with a colon. For example:

ubuntu:24.04
ubuntu-minimal:24.04
images:alpine/edge
local:ed7509d7e83f

Here, ubuntu, ubuntu-minimal, and images are built-in image registries, and local refers to an image in the local image store.

Select a default remote

If you specify an image name without the name of the remote, the default image server is used.

To see which server is configured as the default image server, enter the following command:

lxc remote get-default

To select a different remote as the default image server, enter the following command:

lxc remote switch <remote_name>