# nodus.image

> The Modal-shaped `Image` builder (resources.md §5.3).

Source: https://nodus-platform-site.pages.dev/docs/reference/python/nodus-image/
Build revision: 211ad9f836655b1c3a2668c4693e442471f28614

<!-- Generated by scripts/gen-reference.mjs from the SDK docstrings (griffe). Do not edit: run make gen. -->

The Modal-shaped `Image` builder (resources.md §5.3).

A chain of immutable builder calls describes an `Image` spec. Nothing touches the network until the image is used by a published App or `.build()` is called; the Image object is named by the hash of its spec, so an identical chain reuses the built digest.

## `Image`

```python
class Image(*, base: str | None = None, dockerfile: Obj | None = None, python: str | None = None, steps: tuple[tuple[Any, ...], ...] = , existing: str | None = None, pull_secrets: tuple[str, ...] = ) -> None
```

### `Image.add_local_dir`

```python
add_local_dir(local_path: str | Path, remote_path: str) -> _Image
```

### `Image.add_local_file`

```python
add_local_file(local_path: str | Path, remote_path: str) -> _Image
```

### `Image.add_local_python_source`

```python
add_local_python_source(*modules: str) -> _Image
```

Copy importable local modules or packages to `/workspace/<name>`, where the worker imports from.

### `Image.apt_install`

```python
apt_install(*packages: str) -> _Image
```

### `Image.build`

```python
build(*, show_logs: bool = True) -> _Image
```

Build now (otherwise the first use builds it), streaming the build log; raises `ImageBuildFailed`.

### `Image.debian_slim`

```python
debian_slim(python_version: str | None = None) -> _Image
```

The catalog `nodus/python:<version>` image; defaults to the caller’s Python minor version.

### `Image.digest`

Type: `str | None`

The built digest, known after `.build()` or after an App that uses the image was published.

### `Image.env`

```python
env(values: dict[str, str]) -> _Image
```

### `Image.from_dockerfile`

```python
from_dockerfile(path: str | Path, context: str | Path = '.') -> _Image
```

### `Image.from_name`

```python
from_name(name: str) -> _Image
```

An Image object that already exists in the project.

### `Image.from_registry`

```python
from_registry(ref: str, secret: Any = None) -> _Image
```

Start from an OCI reference or a catalog image (`nodus/pytorch:2.8-cuda12.8`).

### `Image.name`

Type: `str | None`

### `Image.pip_install`

```python
pip_install(*packages: str, index_url: str | None = None, extra_index_urls: list[str] | None = None) -> _Image
```

### `Image.python`

Type: `str | None`

### `Image.run_commands`

```python
run_commands(*commands: str) -> _Image
```

### `Image.uv_pip_install`

```python
uv_pip_install(*packages: str, index_url: str | None = None, extra_index_urls: list[str] | None = None) -> _Image
```

### `Image.uv_sync`

```python
uv_sync(project_dir: str | Path = '.', frozen: bool = True) -> _Image
```

### `Image.workdir`

```python
workdir(path: str) -> _Image
```