How to use remote images - Incus documentation
Description: The incus CLI command can support several image servers and comes pre-configured with our own. See Default image server for an overview. List configured remotes: To see all configured remote server...

Skip to content
Back to top
View this page

# How to use remote images

The `incus` CLI command can support several image servers and comes pre-configured with our own. See Default image server for an overview.

## List configured remotes

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

    incus remote list

Remote servers that use the simple streams format are pure image servers. Servers that use the `incus` format are Incus servers, which either serve solely as image servers or might provide some images in addition to serving as regular Incus servers. See Image server types for more information.

## List available images on a remote

To list all remote images on a server, enter the following command:

    incus image list <remote>:

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

## Add a remote server

How to add a remote depends on the protocol that the server uses.

### Add a simple streams server

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

    incus remote add <remote_name> <URL> --protocol=simplestreams

The URL must use HTTPS.

### Add a remote Incus server

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

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

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

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

    incus remote add my-remote 192.0.2.10

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

### Add a remote OCI compliant server (i.e. Docker Hub)

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

    incus remote add <remote_name> <URL> --protocol=oci

The URL must use HTTPS.

For example, enter the following command to add Docker Hub as a remote:

    incus remote add oci-docker https://docker.io --protocol=oci

To log in, use a token with `--token <token>`.

For example, enter the following command to add your custom container registry with your own token as a remote:

    incus remote add oci-myregistry https://code.example.org --token abcMyToken --protocol=oci

## Reference an image

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

    images:debian/12
    images:debian/12
    local:ed7509d7e83f

## 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:

    incus remote get-default

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

    incus remote switch <remote_name>