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

# nsc build

Build container images using [Namespace Remote Builders](/docs/solutions/docker-builders).

`build` builds a container image using provided `Dockerfile` and a "context".
A build's context is the set of files located in the specified `PATH`. The built
image can be either pushed to the target image registry or loaded to the local
docker registry.

## Usage

```bash theme={null}
nsc build PATH [--build-arg <arg[,arg]>] [-f <Dockerfile>] [--load] [-n <name[,name]>] [--output-local <path>] [--platform <platform[,platform]>] [--push] [--secret <id=mysecret[,src=/local/secret]>] [-t <tag[,tag]>]
```

### Example

The following builds an image with name **app** using
docker file in the current directory (e.g. `./Dockerfile`) and pushes it to the user's
Workspace Container Registry (e.g. `nscr.io/8enum0hp1l5ii`).

```bash theme={null}
nsc build . --name app --push
```

```text nocopy Output theme={null}
Pushed for linux/amd64:
  nscr.io/8enum0hp1l5ii/app:latest
```

You can tag and push the container image to any Container Registry of your choice.
For example, the following would push to GitHub Container Registry.

```bash theme={null}
nsc build . --tag ghcr.io/apprepo/app --push
```

```text nocopy Output theme={null}
Pushed for linux/amd64:
  ghcr.io/apprepo/app:latest
```

`nsc build` uses your local Docker credentials provider. So to push images to container registries, you need to log in with `docker login`

## Available Commands

* **[logs](/docs/reference/cli/build-logs)** - Print logs for a build.

## Options

<h3 id="--file--f-dockerfile">
  \--file, -f \<Dockerfile>
</h3>

To specify a Dockerfile to build. By default `PATH/Dockerfile` is used.

<h3 id="--tag--t-tagtag">
  \--tag, -t \<tag\[,tag]>
</h3>

Set the image name and optionally a tag (format: "name:tag"). This option can
accept multiple values as an input separated by a comma.

<h3 id="--name--n-namename">
  \--name, -n \<name\[,name]>
</h3>

Similarly to `-t`, it sets the image name and optionally a tag (format: "name:tag").
It automatically specifies the Workspace Registry repository as part of the tags (i.e. `nscr.io/<workspace ID>`).
This option can accept multiple values as an input separated by a comma.

<h3 id="--build-arg-argarg">
  \--build-arg \<arg\[,arg]>
</h3>

This flag allows you to pass the build-time variables that are accessed like
regular environment variables in the `RUN` instruction of the Dockerfile.

<h3 id="--platform-platformplatform">
  \--platform \<platform\[,platform]>
</h3>

Set the target platform for the build. The default value is the platform of the
local host. The value takes the form of `os/arch` or os/arch/variant.
For example, `linux/amd64` or `linux/arm/v7`.

This option can accept multiple values as an input separated by a comma. With
multiple values the result will be built for all the specified platforms and
joined together into a single manifest list.

<h3 id="--push">
  \--push
</h3>

Specify the option to push the build result to registry. `nsc` will push images
for all the provided with `-t` or `-n` options tags.

<h3 id="--load">
  \--load
</h3>

Specify the option to automatically load the single-platform build result to
the local docker registry. Note that `--load` doesn't support multi-platform
image builds.

<h3 id="--output-local-path">
  \--output-local \<path>
</h3>

If set, writes the build output directly to the specified local directory
instead of pushing the image to a registry or loading it into the local
Docker registry. Use this when you need the raw build artifacts on disk
rather than a container image.

<h3 id="--secret">
  \--secret
</h3>

A secret to expose to the build. Format: `id=ID[,src=FILEPATH][,env=VARIABLE]`.
See also [build secrets usage](https://docs.docker.com/build/building/secrets/#using-build-secrets).