# Local Image Builder

The local image builder is an [image builder](https://docs.zenml.io/stacks/stack-components/image-builders) flavor that comes built-in with ZenML and uses the local Docker installation on your client machine to build container images.

{% hint style="info" %}
ZenML uses the official Docker Python library to build and push your images. This library loads its authentication credentials to push images from the default config location: `$HOME/.docker/config.json`. If your Docker configuration is stored in a different directory, you can use the environment variable `DOCKER_CONFIG` to override this behavior:

```shell
export DOCKER_CONFIG=/path/to/config_dir
```

The directory that you specify here must contain your Docker configuration in a file called `config.json`.
{% endhint %}

### When to use it

You should use the local image builder if:

* you're able to install and use [Docker](https://www.docker.com) on your client machine.
* you want to use remote components that require containerization without the additional hassle of configuring infrastructure for an additional component.

### How to deploy it

The local image builder comes with ZenML and works without any additional setup.

### How to use it

To use the Local image builder, we need:

* [Docker](https://www.docker.com) installed and running.
* The Docker client authenticated to push to the container registry that you intend to use in the same stack.

We can then register the image builder and use it to create a new stack:

```shell
zenml image-builder register <NAME> --flavor=local

# Register and activate a stack with the new image builder
zenml stack register <STACK_NAME> -i <NAME> ... --set
```

#### Use the Docker CLI for builds (subprocess mode)

By default, the local image builder uses the Docker Python SDK to run builds. You can alternatively configure it to call the Docker CLI (`docker build`) via a subprocess. This can help if you require some options that are only available for Docker BuildKit, which is not supported in the Python SDK yet.

Enable subprocess mode when registering or updating the component:

```shell
# Register with subprocess mode enabled
zenml image-builder register <NAME> --flavor=local --use_subprocess_call=true

# Or update an existing local image builder
zenml image-builder update <NAME> --use_subprocess_call=true
```

In subprocess mode, the build options passed via `DockerSettings` are handled in the following way:

* The `buildargs`, `labels` dictionaries are passed as `--build-arg KEY=VALUE` and `--label KEY=VALUE` respectively
* Lists will pass multiple command line arguments with the same name for all values
* `True` boolean values means the argument will be passed without any value (`--KEY`)
* All other values are converted to a string and passed as `--KEY VALUE`

For more information and a full list of configurable attributes of the local image builder, check out the [SDK Docs](https://sdkdocs.zenml.io/latest/core_code_docs/core-image_builders.html#zenml.image_builders.local_image_builder) .

<figure><img src="https://static.scarf.sh/a.png?x-pxid=f0b4f458-0a54-4fcd-aa95-d5ee424815bc" alt="ZenML Scarf"><figcaption></figcaption></figure>