---
title: "Kapitan compile: Render Targets to Output Files"
description: "Learn how the kapitan compile command merges inventory and inputs to generate your output files."
---

# :kapitan-logo: **CLI Reference** | `kapitan compile`

## `kapitan compile`

Merges inventory and inputs and produces generated files in the output folder (`/compiled` by default)

## Compile all targets

!!! example ""

    ```shell
    kapitan compile
    ```

    ??? example "click to expand output"
        ```text
        Compiled mysql-generator-fetch (0.18s)
        Compiled vault (0.25s)
        Compiled pritunl (0.22s)
        Compiled gke-pvm-killer (0.05s)
        Compiled examples (0.30s)
        Compiled mysql (0.08s)
        Compiled postgres-proxy (0.06s)
        Compiled echo-server (0.06s)
        Compiled global (0.03s)
        Compiled guestbook-argocd (0.08s)
        Compiled tutorial (0.13s)
        Compiled kapicorp-project-123 (0.03s)
        Compiled kapicorp-demo-march (0.03s)
        Compiled kapicorp-terraform-admin (0.03s)
        Compiled sock-shop (0.32s)
        Compiled tesoro (0.09s)
        Compiled dev-sockshop (0.32s)
        Compiled prod-sockshop (0.38s)
        Compiled argocd (2.29s)
        ```

## Selective compilation

### Using target names

Compiles one or more targets selected by name using `--targets` or `-t`

!!! example ""

    ```shell
    kapitan compile -t mysql tesoro
    ```

    ??? example "click to expand output"
        ```shell
        Compiled mysql (0.06s)
        Compiled tesoro (0.09s)
        ```

### Using labels

Compiles one or more targets selected matching **labels** with  `--labels` or `-l`

!!! info

    This works if you have labelled your targets using the following syntax:

    ```yaml
    parameters:
      ...
      kapitan:
        ...
        labels:
          customer: acme
    ```

    see [**Labels**](../inventory/advanced.md#target-labels) for more details

```shell
$ kapitan compile -l customer=acme
Compiled acme-project (0.14s)
Compiled acme-pipelines (0.10s)
```

## Fetch on compile

Use the `--fetch` flag to fetch [**External Dependencies**](../external_dependencies.md).

```shell
kapitan compile --fetch
```

This will download the dependencies according to their configurations
By default, kapitan does not overwrite an existing item with the same name as that of the fetched inventory items.

Use the `--force-fetch` flag to force fetch (update cache with freshly fetched items) and overwrite inventory items of the same name in the `output_path`.

```shell
kapitan compile --force-fetch
```

Use the `--cache` flag to cache the fetched items in the `.dependency_cache` directory in the root project directory.

```shell
kapitan compile --cache --fetch
```

## Embed references

By default, **Kapitan** references are stored encrypted (for backends that support encription) in the configuration repository under the `/refs` directory.

For instance, a reference tag `?{gpg:targets/minikube-mysql/mysql/password:ec3d54de}` would point to a phisical file on disk under `/refs` like:

!!! example "`refs/targets/minikube-mysql/mysql/password`"

    ```shell
    data: hQEMA8uOJKdm07XTAQgAp5i [[ CUT ]] BwqYc3g7PI09HCJZdU=
    encoding: base64
    recipients:
    - fingerprint: D9234C61F58BEB3ED8552A57E28DC07A3CBFAE7C
    type: gpg
    ```

The `--embed-refs` flags tells **Kapitan** to embed these references on compile, alongside the generated output. By doing so, compiled output is self-contained and can be revealed by [**Tesoro**](https://github.com/kapicorp/tesoro) or other tools.

!!! example ""

    ```shell
    kapitan compile --embed-refs
    ```

    See how the compiled output for this specific target changes to embed the actul encrypted content, (marked by `?{gpg: :embedded}` to indicate it is a **gpg** reference) rather than just holding a reference to it (like in this case `?{gpg:targets/minikube-mysql/mysql/password:ec3d54de}` which points to ).

    ??? example "click to expand output"
        ```shell
        diff --git a/examples/kubernetes/compiled/minikube-mysql/manifests/mysql_app.yml b/examples/kubernetes/compiled/minikube-mysql/manifests/mysql_app.yml
        [[ CUT ]]
        apiVersion: v1
        data:
        -  MYSQL_ROOT_PASSWORD: ?{gpg:targets/minikube-mysql/mysql/password:ec3d54de}
        -  MYSQL_ROOT_PASSWORD_SHA256: ?{gpg:targets/minikube-mysql/mysql/password_sha256:122d2732}
        +  MYSQL_ROOT_PASSWORD: ?{gpg:eyJkYXRhIjogImhR [[ CUT ]] gInR5cGUiOiAiZ3BnIn0=:embedded}
        +  MYSQL_ROOT_PASSWORD_SHA256: ?{gpg:eyJkYXRhI [[ CUT ]] eXBlIjogImdwZyJ9:embedded}
        ```

## Fast YAML emission with rapidyaml

For YAML-heavy compiles (large Helm-style component trees, big Kubernetes
manifests, hundreds of targets, etc.) the YAML emitter itself can become a
meaningful share of total compile time. Kapitan ships an *opt-in* fast
path backed by [rapidyaml](https://github.com/biojppm/rapidyaml) (a C++ YAML
library), enabled with `--yaml-use-rapidyaml`.

!!! example ""

    ```shell
    pip install kapitan[rapidyaml]
    kapitan compile --yaml-use-rapidyaml
    ```

    On a realistic Kubernetes Deployment manifest the rapidyaml emitter is
    around **6x faster** than the default PyYAML emitter.

!!! note

    * Compiled output is **deterministic** and **semantically equivalent**
      to the default PyYAML output: mapping keys are still sorted
      alphabetically and every scalar round-trips to the same Python
      object.
    * Cosmetic differences are possible (e.g. rapidyaml may single-quote a
      few scalars that PyYAML leaves plain, like `image: 'mysql:latest'`).
      Existing fixtures comparing exact bytes may need regenerating.
    * If the `rapidyaml` package is not installed, the flag is ignored
      with a one-time startup warning and PyYAML is used.
    * Documents containing ASCII control characters automatically fall
      back to PyYAML for that single document (rapidyaml does not escape
      them in double-quoted scalars).

## Flags

The table below is generated from **Kapitan**'s argument parser at docs-build time, so it always matches the installed version. See also the [global flags](kapitan_flags.md) accepted by every command, and the [`.kapitan` dotfile](kapitan_dotfile.md) to set any of these permanently.

<!-- kapitan-flags:command:compile -->
