---
title: "Image"
hideTitleOnPage: true
---

## ImageService

```python
class ImageService()
```

Image build/pull/list namespace.

#### ImageService.\_\_init\_\_

```python
def __init__(impl: AsyncImageService, bridge: SyncBridge) -> None
```

#### ImageService.build

```python
def build(builder: ImageBuilder,
          /,
          *,
          name: Optional[str] = None,
          idle_expiry_seconds: Optional[int] = None,
          region: Optional[str] = None,
          cpu_arch: Optional[str] = None,
          timeout: Optional[float] = None) -> Image
```

Build (or import) an image from an `ImageBuilder` declaration.

#### ImageService.delete

```python
def delete(image_id: str) -> None
```

#### ImageService.follow\_build\_logs

```python
def follow_build_logs(image_id: str,
                      *,
                      on_logs: _LogsCallback,
                      on_event: Optional[_EventCallback] = None,
                      cursor: Optional[str] = None,
                      timeout: Optional[float] = None) -> BuildLogFollowResult
```

Observe a submitted image build. Timeout is in seconds, not execution TTL.

#### ImageService.get

```python
def get(image_id: str,
        *,
        wait: Literal['ready'] | None = None,
        timeout: Optional[float] = None) -> Image
```

#### ImageService.iter

```python
def iter(*,
         anonymous: bool = False,
         sandbox_id: Optional[str] = None,
         name: Optional[str] = None,
         cursor: Optional[str] = None,
         limit: Optional[int] = None,
         platform: Optional[Literal['true', 'false', 'any']] = None) -> Iterator[Image]
```

#### ImageService.list

```python
def list(*,
         anonymous: bool = False,
         sandbox_id: Optional[str] = None,
         name: Optional[str] = None,
         cursor: Optional[str] = None,
         limit: Optional[int] = None,
         platform: Optional[Literal['true', 'false', 'any']] = None) -> ListResult[Image]
```

List images (`GET /images`).

#### ImageService.promote

```python
def promote(image_id: str, name: str) -> Image
```

Name an ANONYMOUS image, making it permanent (`PATCH /images/{id}`).

#### ImageService.pull

```python
def pull(image: str,
         *,
         name: Optional[str] = None,
         region: Optional[str] = None,
         timeout: Optional[float] = None) -> Image
```

## AsyncImageService

```python
class AsyncImageService()
```

Image build/pull/list namespace.

#### AsyncImageService.\_\_init\_\_

```python
def __init__(transport: AsyncTransport) -> None
```

#### AsyncImageService.follow\_build\_logs

```python
async def follow_build_logs(image_id: str,
                            *,
                            on_logs: _LogsCallback,
                            on_event: Optional[_EventCallback] = None,
                            cursor: Optional[str] = None,
                            timeout: Optional[float] = None) -> BuildLogFollowResult
```

Observe a submitted image build. Timeout is in seconds, not execution TTL.

#### AsyncImageService.build

```python
async def build(builder: ImageBuilder,
                /,
                *,
                name: Optional[str] = None,
                idle_expiry_seconds: Optional[int] = None,
                region: Optional[str] = None,
                cpu_arch: Optional[str] = None,
                timeout: Optional[float] = None) -> Image
```

Build (or import) an image from an `ImageBuilder` declaration.

The builder is the only way to say WHAT to build — `ImageBuilder.
from_dockerfile(...)`, `.from_registry(...)`, or the fluent
`.run_commands` / `.env` / `.workdir` chain — in both SDKs
(parity with TypeScript's `images.build(builder, options)`). `name`
omitted makes the image anonymous; `idle_expiry_seconds` is then its
idle-retention window — deleted once that long has passed without a
sandbox being created from it (every create restarts the clock);
omitted ⇒ the server maximum (`DAYTONA_ANON_IMAGE_MAX_IDLE`).

#### AsyncImageService.pull

```python
async def pull(image: str,
               *,
               name: Optional[str] = None,
               region: Optional[str] = None,
               timeout: Optional[float] = None) -> Image
```

#### AsyncImageService.get

```python
async def get(image_id: str,
              *,
              wait: Literal['ready'] | None = None,
              timeout: Optional[float] = None) -> Image
```

#### AsyncImageService.promote

```python
async def promote(image_id: str, name: str) -> Image
```

Name an ANONYMOUS image, making it permanent (`PATCH /images/{id}`).

Promotion only: an image that already has a name answers 409 — renaming
a named image is not offered (sandboxes reference images by id, so a
rename would silently relabel every sandbox created from it).

#### AsyncImageService.delete

```python
async def delete(image_id: str) -> None
```

#### AsyncImageService.list

```python
async def list(*,
               anonymous: bool = False,
               sandbox_id: Optional[str] = None,
               name: Optional[str] = None,
               cursor: Optional[str] = None,
               limit: Optional[int] = None,
               platform: Optional[Literal['true', 'false', 'any']] = None) -> ListResult[Image]
```

List images (`GET /images`).

`platform` picks the platform images the operator publishes for every
project: `"false"` (the server default) lists the project's own
images, `"true"` lists only the non-deprecated platform images (the
default one carries `default=True`), and `"any"` lists both.

#### AsyncImageService.iter

```python
async def iter(*,
               anonymous: bool = False,
               sandbox_id: Optional[str] = None,
               name: Optional[str] = None,
               cursor: Optional[str] = None,
               limit: Optional[int] = None,
               platform: Optional[Literal['true', 'false', 'any']] = None) -> AsyncIterator[Image]
```

## BuildLogFollowResult

```python
@dataclass(frozen=True)
class BuildLogFollowResult()
```

**Attributes**:

- `status` _str_
- `reason` _BuildLogDoneReason_
- `output_complete` _bool_
- `cursor` _str \| None = None_
- `raw_reason` _str \| None = None_

## BuildLogStateEvent

```python
@dataclass(frozen=True)
class BuildLogStateEvent()
```

**Attributes**:

- `status` _str_
- `error` _str \| None = None_
- `deadline_at` _str \| None = None_
- `type` _Literal\['state'\] = 'state'_

## BuildLogChunkEvent

```python
@dataclass(frozen=True)
class BuildLogChunkEvent()
```

**Attributes**:

- `data_base64` _str_
- `start_offset` _str_
- `next_offset` _str_
- `cursor` _str_
- `type` _Literal\['log'\] = 'log'_

## BuildLogGapEvent

```python
@dataclass(frozen=True)
class BuildLogGapEvent()
```

**Attributes**:

- `requested_offset` _str_
- `first_available_offset` _str_
- `dropped_bytes` _str_
- `cursor` _str_
- `reason` _BuildLogGapReason = 'truncated'_
- `type` _Literal\['gap'\] = 'gap'_
- `raw_reason` _str \| None = None_

## BuildLogUnavailableEvent

```python
@dataclass(frozen=True)
class BuildLogUnavailableEvent()
```

**Attributes**:

- `reason` _str_
- `type` _Literal\['unavailable'\] = 'unavailable'_

## BuildLogSourceChangedEvent

```python
@dataclass(frozen=True)
class BuildLogSourceChangedEvent()
```

**Attributes**:

- `reason` _str_
- `type` _Literal\['source_changed'\] = 'source_changed'_

## BuildLogDoneEvent

```python
@dataclass(frozen=True)
class BuildLogDoneEvent()
```

**Attributes**:

- `result` _BuildLogFollowResult_
- `type` _Literal\['done'\] = 'done'_

## BuildLogErrorEvent

```python
@dataclass(frozen=True)
class BuildLogErrorEvent()
```

**Attributes**:

- `error` _str_
- `code` _str_
- `retryable` _bool_
- `trace_id` _str \| None = None_
- `type` _Literal\['error'\] = 'error'_

## ImageBuilder

```python
@dataclass(frozen=True, slots=True)
class ImageBuilder()
```

#### ImageBuilder.from\_registry

```python
@classmethod
def from_registry(ref: str) -> Self
```

#### ImageBuilder.from\_dockerfile

```python
@classmethod
def from_dockerfile(content: str) -> Self
```

#### ImageBuilder.pip\_install

```python
def pip_install(*packages: str) -> Self
```

#### ImageBuilder.run\_commands

```python
def run_commands(*commands: str) -> Self
```

#### ImageBuilder.env

```python
@overload
def env(name: str, value: str, /) -> Self
```

#### ImageBuilder.env

```python
@overload
def env(values: Mapping[str, str], /) -> Self
```

#### ImageBuilder.workdir

```python
def workdir(path: str, /) -> Self
```

#### ImageBuilder.build\_request\_source

```python
def build_request_source() -> tuple[dict[str, str] | None, str | None]
```

#### ImageBuilder.render\_dockerfile

```python
def render_dockerfile() -> str
```

Render the Dockerfile the build request carries.

Byte-identical to TypeScript's `ImageBuilder.toDockerfile()` for the
same builder: one line per layer, a single trailing newline (a POSIX
text file), no trailing whitespace. The text is the build's content
key, so the two SDKs must agree to the byte or the same build would
dedupe differently across them.

## ImageRef

```python
@dataclass(frozen=True, slots=True)
class ImageRef()
```

**Attributes**:

- `id` _str_
- `name` _Optional\[str\] = None_

## Image

```python
@dataclass(frozen=True, slots=True)
class Image()
```

**Attributes**:

- `id` _str_
- `name` _Optional\[str\]_
- `status` _str_
- `region` _str_
- `anonymous` _bool_
- `retention` _ArtifactRetention_
- `var_class` _str_
- `available_in` _list\[str\]_
- `origin` _str_
- `created_at` _Optional\[str\] = None_
- `error` _Optional\[str\] = None_
- `expires_at` _Optional\[str\] = None_
- `source` _Optional\[ImageSource\] = None_
- `bytes` _Optional\[int\] = None_
- `layer_count` _Optional\[int\] = None_
- `cursor` _Optional\[str\] = None_
- `format_version` _Optional\[int\] = None_
- `format_outdated` _bool = False_
- `platform` _bool = False_
- `default` _bool = False_
- `deprecated` _bool = False_
- `updated_at` _Optional\[str\] = None_
- `disk_mib` _Optional\[int\] = None_
- `raw_retention` _str = field(default='', kw_only=True)_

## BuildLogDoneReason

```python
BuildLogDoneReason = Literal['terminal', 'deadline', 'not_applicable', 'resource_deleted', 'unknown']
```

## BuildLogGapReason

```python
BuildLogGapReason = Literal['truncated', 'unknown']
```

## BuildLogEvent

```python
BuildLogEvent = BuildLogStateEvent | BuildLogChunkEvent | BuildLogGapEvent | BuildLogUnavailableEvent | BuildLogSourceChangedEvent | BuildLogDoneEvent | BuildLogErrorEvent
```

## ImageBuildResponse

```python
ImageBuildResponse = _gen.api.AsyncOperation
```

## ImageJob

```python
ImageJob = ImageBuildResponse
```

## ImageDto

```python
ImageDto = _gen.api.ImageListItem
```

## ArtifactRetention

```python
ArtifactRetention = Literal['permanent', 'idle', 'unknown']
```

## ImageSource

```python
ImageSource = Union[RegistryImageSource, DockerfileImageSource, NamedImageSource, ManifestImageSource]
```