Skip to content

Images API

The ImagesAPI client provides methods for managing Incus images.

Usage

from incus_sdk import Client

async with Client() as client:
    # List all images
    images = await client.images.list()

    # Get an image by fingerprint
    image = await client.images.get("abcdef123456")

    # Create an image from a file
    with open("image.tar.gz", "rb") as f:
        image_data = f.read()

    await client.images.create(
        image_data=image_data,
        filename="image.tar.gz",
        properties={"description": "My custom image"},
        wait=True
    )

    # Export an image to a file
    await client.images.export("abcdef123456", "exported_image.tar.gz")

    # Create an alias for an image
    await client.images.create_alias(
        name="my-image",
        target="abcdef123456",
        description="My custom image"
    )

    # Delete an image
    await client.images.delete("abcdef123456", wait=True)

Class Documentation

API client for Incus images.

Source code in incus_sdk/api/images.py 
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
class ImagesAPI:
    """API client for Incus images."""

    def __init__(self, client: APIClient):
        """
        Initialize a new ImagesAPI client.

        Args:
            client: The base API client.
        """
        self.client = client

    async def list(self, recursion: int = 1) -> List[Image]:
        """
        List all images.

        Args:
            recursion: Level of recursion for the response.

        Returns:
            List[Image]: List of images.
        """
        params = {"recursion": recursion}
        response = await self.client.get("/1.0/images", params=params)

        images = []
        for image_data in response.get("metadata", []):
            images.append(Image(client=self, **image_data))

        return images

    async def get(self, fingerprint: str) -> Image:
        """
        Get an image by fingerprint.

        Args:
            fingerprint: Fingerprint of the image.

        Returns:
            Image: The image.
        """
        response = await self.client.get(f"/1.0/images/{fingerprint}")
        return Image(client=self, **response.get("metadata", {}))

    async def create(
        self,
        image_data: bytes,
        filename: str = None,
        public: bool = False,
        auto_update: bool = False,
        properties: Dict[str, str] = None,
        wait: bool = False,
    ) -> Union[Dict[str, Any], Image]:
        """
        Create a new image.

        Args:
            image_data: Image data.
            filename: Name of the image file.
            public: Whether the image is public.
            auto_update: Whether the image auto-updates.
            properties: Image properties.
            wait: Whether to wait for the operation to complete.

        Returns:
            Union[Dict[str, Any], Image]: The operation response or the created image.
        """
        headers = {}
        if filename:
            headers["X-Incus-Filename"] = filename

        params = {}
        if public:
            params["public"] = "1"
        if auto_update:
            params["auto_update"] = "1"
        if properties:
            for key, value in properties.items():
                params[f"properties.{key}"] = value

        response = await self.client.post(
            "/1.0/images", data=image_data, params=params, headers=headers
        )

        if wait and "id" in response.get("metadata", {}):
            await self.client.wait_for_operation(response["metadata"]["id"])
            # Get the fingerprint from the operation metadata
            operation = await self.client.get(
                f"/1.0/operations/{response['metadata']['id']}"
            )
            fingerprint = operation.get("metadata", {}).get("fingerprint")
            if fingerprint:
                return await self.get(fingerprint)

        return response

    async def delete(self, fingerprint: str, wait: bool = False) -> Dict[str, Any]:
        """
        Delete an image.

        Args:
            fingerprint: Fingerprint of the image.
            wait: Whether to wait for the operation to complete.

        Returns:
            Dict[str, Any]: The operation response.
        """
        response = await self.client.delete(f"/1.0/images/{fingerprint}")

        if wait and "id" in response.get("metadata", {}):
            return await self.client.wait_for_operation(response["metadata"]["id"])

        return response

    async def update(
        self, fingerprint: str, properties: Dict[str, Any], wait: bool = False
    ) -> Dict[str, Any]:
        """
        Update an image.

        Args:
            fingerprint: Fingerprint of the image.
            properties: New properties.
            wait: Whether to wait for the operation to complete.

        Returns:
            Dict[str, Any]: The operation response.
        """
        response = await self.client.patch(
            f"/1.0/images/{fingerprint}", data=properties
        )

        if wait and "id" in response.get("metadata", {}):
            return await self.client.wait_for_operation(response["metadata"]["id"])

        return response

    async def export(self, fingerprint: str, target_path: str) -> None:
        """
        Export an image to a file.

        Args:
            fingerprint: Fingerprint of the image.
            target_path: Path to save the exported image.
        """
        response = await self.client.get(f"/1.0/images/{fingerprint}/export")

        async with aiofiles.open(target_path, "wb") as f:
            await f.write(response)

    async def create_alias(
        self, name: str, target: str, description: str = None
    ) -> Dict[str, Any]:
        """
        Create an image alias.

        Args:
            name: Name of the alias.
            target: Target fingerprint.
            description: Description of the alias.

        Returns:
            Dict[str, Any]: The operation response.
        """
        data = {"name": name, "target": target}

        if description:
            data["description"] = description

        return await self.client.post("/1.0/images/aliases", data=data)

    async def delete_alias(self, name: str) -> Dict[str, Any]:
        """
        Delete an image alias.

        Args:
            name: Name of the alias.

        Returns:
            Dict[str, Any]: The operation response.
        """
        return await self.client.delete(f"/1.0/images/aliases/{name}")

    async def get_alias(self, name: str) -> Dict[str, Any]:
        """
        Get an image alias.

        Args:
            name: Name of the alias.

        Returns:
            Dict[str, Any]: The alias.
        """
        return await self.client.get(f"/1.0/images/aliases/{name}")

    async def update_alias(
        self, name: str, target: str = None, description: str = None
    ) -> Dict[str, Any]:
        """
        Update an image alias.

        Args:
            name: Name of the alias.
            target: New target fingerprint.
            description: New description.

        Returns:
            Dict[str, Any]: The operation response.
        """
        data = {}

        if target:
            data["target"] = target
        if description:
            data["description"] = description

        return await self.client.patch(f"/1.0/images/aliases/{name}", data=data)

__init__(client)

Initialize a new ImagesAPI client.

Parameters:

Name Type Description Default
client APIClient

The base API client.

 required
Source code in incus_sdk/api/images.py 
16
17
18
19
20
21
22
23
def __init__(self, client: APIClient):
    """
    Initialize a new ImagesAPI client.

    Args:
        client: The base API client.
    """
    self.client = client

create(image_data, filename=None, public=False, auto_update=False, properties=None, wait=False) async

Create a new image.

Parameters:

Name Type Description Default
image_data bytes

Image data.

 required
filename str

Name of the image file.

 None
public bool

Whether the image is public.

 False
auto_update bool

Whether the image auto-updates.

 False
properties Dict[str, str]

Image properties.

 None
wait bool

Whether to wait for the operation to complete.

 False

Returns:

Type Description
Union[Dict[str, Any], Image]

Union[Dict[str, Any], Image]: The operation response or the created image.
Source code in incus_sdk/api/images.py 
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
async def create(
    self,
    image_data: bytes,
    filename: str = None,
    public: bool = False,
    auto_update: bool = False,
    properties: Dict[str, str] = None,
    wait: bool = False,
) -> Union[Dict[str, Any], Image]:
    """
    Create a new image.

    Args:
        image_data: Image data.
        filename: Name of the image file.
        public: Whether the image is public.
        auto_update: Whether the image auto-updates.
        properties: Image properties.
        wait: Whether to wait for the operation to complete.

    Returns:
        Union[Dict[str, Any], Image]: The operation response or the created image.
    """
    headers = {}
    if filename:
        headers["X-Incus-Filename"] = filename

    params = {}
    if public:
        params["public"] = "1"
    if auto_update:
        params["auto_update"] = "1"
    if properties:
        for key, value in properties.items():
            params[f"properties.{key}"] = value

    response = await self.client.post(
        "/1.0/images", data=image_data, params=params, headers=headers
    )

    if wait and "id" in response.get("metadata", {}):
        await self.client.wait_for_operation(response["metadata"]["id"])
        # Get the fingerprint from the operation metadata
        operation = await self.client.get(
            f"/1.0/operations/{response['metadata']['id']}"
        )
        fingerprint = operation.get("metadata", {}).get("fingerprint")
        if fingerprint:
            return await self.get(fingerprint)

    return response

create_alias(name, target, description=None) async

Create an image alias.

Parameters:

Name Type Description Default
name str

Name of the alias.

 required
target str

Target fingerprint.

 required
description str

Description of the alias.

 None

Returns:

Type Description
Dict[str, Any]

Dict[str, Any]: The operation response.
Source code in incus_sdk/api/images.py 
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
async def create_alias(
    self, name: str, target: str, description: str = None
) -> Dict[str, Any]:
    """
    Create an image alias.

    Args:
        name: Name of the alias.
        target: Target fingerprint.
        description: Description of the alias.

    Returns:
        Dict[str, Any]: The operation response.
    """
    data = {"name": name, "target": target}

    if description:
        data["description"] = description

    return await self.client.post("/1.0/images/aliases", data=data)

delete(fingerprint, wait=False) async

Delete an image.

Parameters:

Name Type Description Default
fingerprint str

Fingerprint of the image.

 required
wait bool

Whether to wait for the operation to complete.

 False

Returns:

Type Description
Dict[str, Any]

Dict[str, Any]: The operation response.
Source code in incus_sdk/api/images.py 
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
async def delete(self, fingerprint: str, wait: bool = False) -> Dict[str, Any]:
    """
    Delete an image.

    Args:
        fingerprint: Fingerprint of the image.
        wait: Whether to wait for the operation to complete.

    Returns:
        Dict[str, Any]: The operation response.
    """
    response = await self.client.delete(f"/1.0/images/{fingerprint}")

    if wait and "id" in response.get("metadata", {}):
        return await self.client.wait_for_operation(response["metadata"]["id"])

    return response

delete_alias(name) async

Delete an image alias.

Parameters:

Name Type Description Default
name str

Name of the alias.

 required

Returns:

Type Description
Dict[str, Any]

Dict[str, Any]: The operation response.
Source code in incus_sdk/api/images.py 
184
185
186
187
188
189
190
191
192
193
194
async def delete_alias(self, name: str) -> Dict[str, Any]:
    """
    Delete an image alias.

    Args:
        name: Name of the alias.

    Returns:
        Dict[str, Any]: The operation response.
    """
    return await self.client.delete(f"/1.0/images/aliases/{name}")

export(fingerprint, target_path) async

Export an image to a file.

Parameters:

Name Type Description Default
fingerprint str

Fingerprint of the image.

 required
target_path str

Path to save the exported image.

 required
Source code in incus_sdk/api/images.py 
150
151
152
153
154
155
156
157
158
159
160
161
async def export(self, fingerprint: str, target_path: str) -> None:
    """
    Export an image to a file.

    Args:
        fingerprint: Fingerprint of the image.
        target_path: Path to save the exported image.
    """
    response = await self.client.get(f"/1.0/images/{fingerprint}/export")

    async with aiofiles.open(target_path, "wb") as f:
        await f.write(response)

get(fingerprint) async

Get an image by fingerprint.

Parameters:

Name Type Description Default
fingerprint str

Fingerprint of the image.

 required

Returns:

Name Type Description
Image Image

The image.
Source code in incus_sdk/api/images.py 
44
45
46
47
48
49
50
51
52
53
54
55
async def get(self, fingerprint: str) -> Image:
    """
    Get an image by fingerprint.

    Args:
        fingerprint: Fingerprint of the image.

    Returns:
        Image: The image.
    """
    response = await self.client.get(f"/1.0/images/{fingerprint}")
    return Image(client=self, **response.get("metadata", {}))

get_alias(name) async

Get an image alias.

Parameters:

Name Type Description Default
name str

Name of the alias.

 required

Returns:

Type Description
Dict[str, Any]

Dict[str, Any]: The alias.
Source code in incus_sdk/api/images.py 
196
197
198
199
200
201
202
203
204
205
206
async def get_alias(self, name: str) -> Dict[str, Any]:
    """
    Get an image alias.

    Args:
        name: Name of the alias.

    Returns:
        Dict[str, Any]: The alias.
    """
    return await self.client.get(f"/1.0/images/aliases/{name}")

list(recursion=1) async

List all images.

Parameters:

Name Type Description Default
recursion int

Level of recursion for the response.

 1

Returns:

Type Description
List[Image]

List[Image]: List of images.
Source code in incus_sdk/api/images.py 
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
async def list(self, recursion: int = 1) -> List[Image]:
    """
    List all images.

    Args:
        recursion: Level of recursion for the response.

    Returns:
        List[Image]: List of images.
    """
    params = {"recursion": recursion}
    response = await self.client.get("/1.0/images", params=params)

    images = []
    for image_data in response.get("metadata", []):
        images.append(Image(client=self, **image_data))

    return images

update(fingerprint, properties, wait=False) async

Update an image.

Parameters:

Name Type Description Default
fingerprint str

Fingerprint of the image.

 required
properties Dict[str, Any]

New properties.

 required
wait bool

Whether to wait for the operation to complete.

 False

Returns:

Type Description
Dict[str, Any]

Dict[str, Any]: The operation response.
Source code in incus_sdk/api/images.py 
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
async def update(
    self, fingerprint: str, properties: Dict[str, Any], wait: bool = False
) -> Dict[str, Any]:
    """
    Update an image.

    Args:
        fingerprint: Fingerprint of the image.
        properties: New properties.
        wait: Whether to wait for the operation to complete.

    Returns:
        Dict[str, Any]: The operation response.
    """
    response = await self.client.patch(
        f"/1.0/images/{fingerprint}", data=properties
    )

    if wait and "id" in response.get("metadata", {}):
        return await self.client.wait_for_operation(response["metadata"]["id"])

    return response

update_alias(name, target=None, description=None) async

Update an image alias.

Parameters:

Name Type Description Default
name str

Name of the alias.

 required
target str

New target fingerprint.

 None
description str

New description.

 None

Returns:

Type Description
Dict[str, Any]

Dict[str, Any]: The operation response.
Source code in incus_sdk/api/images.py 
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
async def update_alias(
    self, name: str, target: str = None, description: str = None
) -> Dict[str, Any]:
    """
    Update an image alias.

    Args:
        name: Name of the alias.
        target: New target fingerprint.
        description: New description.

    Returns:
        Dict[str, Any]: The operation response.
    """
    data = {}

    if target:
        data["target"] = target
    if description:
        data["description"] = description

    return await self.client.patch(f"/1.0/images/aliases/{name}", data=data)

Methods

list

async def list(recursion: int = 1) -> List[Image]

List all images.

Parameters: - recursion: Level of recursion for the response (default: 1).

Returns: - A list of Image objects.

get

async def get(fingerprint: str) -> Image

Get an image by fingerprint.

Parameters: - fingerprint: Fingerprint of the image.

Returns: - An Image object.

create

async def create(
    image_data: bytes,
    filename: str = None,
    public: bool = False,
    auto_update: bool = False,
    properties: Dict[str, str] = None,
    wait: bool = False,
) -> Union[Dict[str, Any], Image]

Create a new image.

Parameters: - image_data: Image data as bytes. - filename: Name of the image file (optional). - public: Whether the image is public (default: False). - auto_update: Whether the image auto-updates (default: False). - properties: Image properties as a dictionary (optional). - wait: Whether to wait for the operation to complete (default: False).

Returns: - If wait is True, returns the created Image object. - If wait is False, returns the operation response as a dictionary.

Example:

# Create an image from a file
import aiofiles

async with aiofiles.open("image.tar.gz", "rb") as f:
    image_data = await f.read()

image = await client.images.create(
    image_data=image_data,
    filename="image.tar.gz",
    properties={
        "description": "My custom image",
        "os": "Ubuntu",
        "release": "22.04"
    },
    public=True,
    wait=True
)

delete

async def delete(
    fingerprint: str, 
    wait: bool = False
) -> Dict[str, Any]

Delete an image.

Parameters: - fingerprint: Fingerprint of the image. - wait: Whether to wait for the operation to complete (default: False).

Returns: - The operation response as a dictionary.

update

async def update(
    fingerprint: str, 
    properties: Dict[str, Any], 
    wait: bool = False
) -> Dict[str, Any]

Update an image.

Parameters: - fingerprint: Fingerprint of the image. - properties: New properties as a dictionary. - wait: Whether to wait for the operation to complete (default: False).

Returns: - The operation response as a dictionary.

export

async def export(
    fingerprint: str, 
    target_path: str
) -> None

Export an image to a file.

Parameters: - fingerprint: Fingerprint of the image. - target_path: Path to save the exported image.

Returns: - None

create_alias

async def create_alias(
    name: str, 
    target: str, 
    description: str = None
) -> Dict[str, Any]

Create an image alias.

Parameters: - name: Name of the alias. - target: Target fingerprint. - description: Description of the alias (optional).

Returns: - The operation response as a dictionary.

delete_alias

async def delete_alias(
    name: str
) -> Dict[str, Any]

Delete an image alias.

Parameters: - name: Name of the alias.

Returns: - The operation response as a dictionary.

get_alias

async def get_alias(
    name: str
) -> Dict[str, Any]

Get an image alias.

Parameters: - name: Name of the alias.

Returns: - The alias information as a dictionary.

update_alias

async def update_alias(
    name: str, 
    target: str, 
    description: str = None
) -> Dict[str, Any]

Update an image alias.

Parameters: - name: Name of the alias. - target: New target fingerprint. - description: New description (optional).

Returns: - The operation response as a dictionary.