---
title: "Image SDK reference"
description: "Customer-hosted cloud features"
---

# Image SDK reference

#### Customer-hosted cloud features

:::note
Some features are only available on customer-hosted clouds. Reach out to [support@anyscale.com](mailto:support@anyscale.com) for info.
:::

## Image SDK

### `anyscale.image.build`

Build an image from a Containerfile.

Returns the URI of the image.

**Arguments**

-   **`containerfile` (str)**: The content of the Containerfile.
-   **`name` (str)**: The name of the image.
-   **`ray_version` (str | None) = None**: The version of Ray to use in the image
-   **`cloud_id` (str | None) = None**: The ID of the Anyscale Cloud. Required for Azure Control Plane only.

**Returns**: str

#### Examples

::::tabs

:::tab[Python]
```python
import anyscale

containerfile = '''
FROM anyscale/ray:2.21.0-py39
RUN pip install --no-cache-dir pandas
'''

image_uri: str = anyscale.image.build(containerfile, name="mycoolimage")
```
:::

::::

### `anyscale.image.get`

The name can contain an optional version tag, i.e., 'name:version'.

If no version is provided, the latest one will be returned.

**Arguments**

-   **`name` (str)**: Get the details of an image.

The name can contain an optional version, e.g., 'name:version'. If no version is provided, the latest one will be used.

-   **`cloud_id` (str | None) = None**: The ID of the Anyscale Cloud. Required for Azure Control Plane only.

**Returns**: [ImageBuild](#imagebuild)

#### Examples

::::tabs

:::tab[Python]
```python
import anyscale

image_status = anyscale.image.get(name="mycoolimage")
```
:::

::::

### `anyscale.image.list`

List images or fetch a single image by ID.

**Arguments**

-   **`image_id` (str | None) = None**: If provided, returns just the image with this ID wrapped in a one-page iterator.
-   **`name` (str | None) = None**: Substring to match against the image name.
-   **`image_name` (str | None) = None**: Substring to match against the resolved image URI (BYOD images only).
-   **`project` (str | None) = None**: Name of the project that owns the image.
-   **`creator_id` (str | None) = None**: Filter images by the creator user ID.
-   **`include_archived` (bool) = False**: Include archived images (default: False).
-   **`include_anonymous` (bool) = False**: Include anonymous (workspace-scoped) images (default: False).
-   **`max_items` (int | None) = None**: Maximum total number of items to yield (default: iterate all).
-   **`page_size` (int | None) = None**: Number of items to fetch per API request (default: API default).
-   **`cloud_id` (str | None) = None**: The ID of the Anyscale Cloud. Required for Azure Control Plane only.

**Returns**: ResultIterator\[[ImageBuild](#imagebuild)\]

#### Examples

::::tabs

:::tab[Python]
```python
import anyscale

for image in anyscale.image.list(max_items=5):
    print(image.name, image.latest_build_revision)
```
:::

::::

### `anyscale.image.register`

Registers a BYOD image with a container image name.

Returns the URI of the image.

**Arguments**

-   **`image_uri` (str)**: The URI of the BYOD image to register.
-   **`name` (str)**: Name for the container image. If the name already exists, a new version will be built. Otherwise, a new container image will be created.
-   **`ray_version` (str | None) = None**: The Ray version (X.Y.Z) specified for this image specified by either an image URI or a containerfile. If you don't specify a Ray version, Anyscale defaults to the latest Ray version available at the time of the Anyscale CLI/SDK release.
-   **`registry_login_secret` (str | None) = None**: Name or identifier of the secret containing credentials to authenticate to the docker registry hosting the image.
-   **`cloud_id` (str | None) = None**: The ID of the Anyscale Cloud to associate this image with. Required for Azure Control Plane only.

**Returns**: str

#### Examples

::::tabs

:::tab[Python]
```python
import anyscale

image_uri: str = anyscale.image.register("docker.io/myuser/myimage:v2", name="mycoolimage")
```
:::

::::

### `anyscale.image.archive`

Archive an image and all of its versions.

Once archived, the image name will no longer be usable in the organization. Archived images can still be viewed using `include_archived=True` in list().

**Arguments**

-   **`name` (str)**: Name of the image to archive. Can include an optional version tag (e.g., 'name:version').
-   **`cloud_id` (str | None) = None**: The ID of the Anyscale Cloud. Required for Azure Control Plane only.

**Returns**: None

#### Examples

::::tabs

:::tab[Python]
```python
import anyscale

anyscale.image.archive(name="my-old-image")
```
:::

::::

## Image models

### `ImageBuildStatus`

Status of an image build operation.

#### Values

-   **`IN_PROGRESS`**: The image build is in progress.
-   **`SUCCEEDED`**: The image build succeeded.
-   **`FAILED`**: The image build failed.
-   **`UNKNOWN`**: The CLI/SDK received an unexpected state from the API server. In most cases, this means you need to update the CLI.

### `ImageBuild`

ImageBuild(id: str, name: str, project\_id: Optional\[str\] = None, creator\_id: Optional\[str\] = None, creator\_email: Optional\[str\] = None, is\_anonymous: bool = False, created\_at: Optional\[datetime.datetime\] = None, last\_modified\_at: Optional\[datetime.datetime\] = None, latest\_build\_id: Optional\[str\] = None, latest\_build\_revision: Optional\[int\] = None, latest\_build\_status: Union\[str, anyscale.image.models.ImageBuildStatus, NoneType\] = None, latest\_image\_uri: Optional\[str\] = None)

#### Fields

-   **`id` (str)**: Unique identifier of the image.
-   **`name` (str)**: Human-readable name assigned to the image (cluster environment).
-   **`project_id` (str | None)**: Project identifier that owns this image, if available.
-   **`creator_id` (str | None)**: Identifier of the user who created the image.
-   **`creator_email` (str | None)**: Email address of the user who created the image, if available.
-   **`is_anonymous` (bool)**: Whether the image was created as an anonymous (workspace-scoped) resource.
-   **`created_at` (datetime | None)**: Timestamp when the image was created.
-   **`last_modified_at` (datetime | None)**: Timestamp when the image was last updated.
-   **`latest_build_id` (str | None)**: Identifier of the most recent build for this image.
-   **`latest_build_revision` (int | None)**: Revision number of the most recent image build (treated as the latest version).
-   **`latest_build_status` (str | [ImageBuildStatus](#imagebuildstatus) | None)**: Status of the most recent image build.
-   **`latest_image_uri` (str | None)**: URI for the latest published image version, if available.

#### Python Methods

```python
def to_dict(self) -> Dict[str, Any]
    """Return a dictionary representation of the model."""
```

#### Examples

::::tabs

:::tab[Python]
```python
import anyscale
from anyscale.image.models import ImageBuild

first_image: ImageBuild = next(anyscale.image.list(max_items=1), None)
```
:::

::::

---

Previous: [Compute config](/reference/sdk/compute-config.md) | Next: [Job queue](/reference/sdk/job-queue.md)