> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baseten.co/llms.txt
> Use this file to discover all available pages before exploring further.

# baseten model image

> Build local Docker images from a model directory

Build a local Docker image, or just its Docker build context, from a model directory.

These commands run entirely locally: they shell out to the truss CLI (via 'uv') to generate the build context and to 'docker' to build the image. They need no authentication and make no Baseten API calls. 'uv' must be on PATH; 'build' also requires 'docker'.

## build

```sh theme={"system"}
baseten model image build [OPTIONS] [-- DOCKER_BUILD_ARGS...]
```

Generate the Docker build context for a model directory and build it into a local Docker image.

The current directory is used by default; pass --dir to point at a model directory elsewhere. The build context is written to a temporary directory that is removed afterward unless --build-dir is given.

Any arguments after '--' are passed through verbatim to 'docker build'. If you supply your own --iidfile there, it is honored and used to report the image ID; otherwise one is injected internally.

### Options

<ParamField body="--build-dir" type="TEXT">
  Directory for the Docker build context. Defaults to a temp dir removed after the build.
</ParamField>

<ParamField body="--cache-mount-id" type="TEXT">
  Enable a persistent apt/pip/uv build cache keyed by this id.
</ParamField>

<ParamField body="--dir" type="TEXT" default=".">
  Model directory.
</ParamField>

<ParamField body="-q, --jq" type="TEXT">
  Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
</ParamField>

<ParamField body="-o, --output" type="TEXT" default="text">
  Output format

  One of: `text`, `json`, `jsonl`, `none`
</ParamField>

<ParamField body="--profile" type="TEXT">
  Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile
</ParamField>

<ParamField body="--root-user" type="BOOL">
  Run the image's container as root instead of the default non-root user.
</ParamField>

<ParamField body="--tag" type="TEXT">
  Image tag. Defaults to '`model_name`:latest' from config.yaml.
</ParamField>

<ParamField body="--truss-executable" type="TEXT">
  Run this truss executable instead of fetching one with uv, e.g. a virtualenv's bin/truss. A value with no path separator is looked up on PATH, so '--truss-executable truss' runs the truss you installed. Defaults to BASETEN\_TRUSS\_EXECUTABLE.
</ParamField>

<ParamField body="--truss-version" type="TEXT">
  Version of truss to fetch and run with 'uv tool run', e.g. 0.18.26. Defaults to BASETEN\_TRUSS\_VERSION, or the latest release. Mutually exclusive with --truss-executable.
</ParamField>

<ParamField body="-v, --verbose" type="BOOL">
  Enable verbose logging
</ParamField>

### Examples

Build the current directory into a local Docker image

```sh theme={"system"}
baseten model image build
```

Build another directory with a custom tag

```sh theme={"system"}
baseten model image build --dir ./my-model --tag my-model:dev
```

Pass extra flags through to docker build

```sh theme={"system"}
baseten model image build -- --no-cache --build-arg FOO=bar
```

### Filter output with `--jq`

Print the built image ID

```sh theme={"system"}
baseten model image build --jq '.image_id'
```

### Output

**Text mode (`--output text`):** Build progress from truss and docker is streamed to stderr. On success a one-line summary is printed to stdout.

**JSON mode (`--output json`):** payload type `cmd.ModelImageBuildResult`.

Under --output json, stdout is the \{image\_id, tag} result. image\_id is empty when it cannot be resolved (e.g. a custom buildx builder that does not write the iidfile).

## prepare

```sh theme={"system"}
baseten model image prepare [OPTIONS] --build-dir DIR
```

Generate the Docker build context (Dockerfile and supporting files) for a model directory into --build-dir, without building an image.

The current directory is used by default; pass --dir to point at a model directory elsewhere. The resulting directory is self-contained and can be built with 'docker build `build-dir`'.

### Options

<ParamField body="--build-dir" type="TEXT" required>
  Directory for the Docker build context. Created if absent and kept.
</ParamField>

<ParamField body="--cache-mount-id" type="TEXT">
  Enable a persistent apt/pip/uv build cache keyed by this id.
</ParamField>

<ParamField body="--dir" type="TEXT" default=".">
  Model directory.
</ParamField>

<ParamField body="-q, --jq" type="TEXT">
  Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
</ParamField>

<ParamField body="-o, --output" type="TEXT" default="text">
  Output format

  One of: `text`, `json`, `jsonl`, `none`
</ParamField>

<ParamField body="--profile" type="TEXT">
  Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile
</ParamField>

<ParamField body="--root-user" type="BOOL">
  Run the image's container as root instead of the default non-root user.
</ParamField>

<ParamField body="--truss-executable" type="TEXT">
  Run this truss executable instead of fetching one with uv, e.g. a virtualenv's bin/truss. A value with no path separator is looked up on PATH, so '--truss-executable truss' runs the truss you installed. Defaults to BASETEN\_TRUSS\_EXECUTABLE.
</ParamField>

<ParamField body="--truss-version" type="TEXT">
  Version of truss to fetch and run with 'uv tool run', e.g. 0.18.26. Defaults to BASETEN\_TRUSS\_VERSION, or the latest release. Mutually exclusive with --truss-executable.
</ParamField>

<ParamField body="-v, --verbose" type="BOOL">
  Enable verbose logging
</ParamField>

### Examples

Write the current directory's build context to ./ctx

```sh theme={"system"}
baseten model image prepare --build-dir ./ctx
```

### Filter output with `--jq`

Print the generated Dockerfile path

```sh theme={"system"}
baseten model image prepare --build-dir ./ctx --jq '.dockerfile'
```

### Output

**Text mode (`--output text`):** Progress from truss is streamed to stderr. On success a one-line summary is printed to stdout.

**JSON mode (`--output json`):** payload type `cmd.ModelImagePrepareResult`.

Under --output json, stdout is the \{build\_dir, dockerfile} result with absolute paths.