+++
title="Customize buildpack behavior with build-time environment variables"
aliases=[
  "/docs/app-developer-guide/environment-variables"
]
weight=2
+++

Environment variables are a common way to configure various buildpacks at build-time.

<!--more-->

Below are a few ways you can do so. All of them use the [samples] repository for
simplicity. The following documentation assumes that all participating buildpack
either use `clear-env = false` as the default in their
[buildpack.toml](https://buildpacks.io/docs/reference/config/buildpack-config/),
or if they use `clear-env = true`, that they merge in filtered user supplied
environment variables.

### Using CLI arguments (`--env`)

The `--env` parameter must be one of the following:

- `VARIABLE=VALUE`
- `VARIABLE`, where the value of `VARIABLE` will be taken from the local environment

##### Example:

1. Set an environment variable
```
export FOO=BAR
```
<!--+- "{{execute}}"+-->

2. Build the app
```
pack build sample-app \
    --env "HELLO=WORLD" \
    --env "FOO" \
    --builder cnbs/sample-builder:resolute \
    --buildpack  samples/buildpacks/hello-world/ \
    --buildpack samples/apps/bash-script/bash-script-buildpack/ \
    --path  samples/apps/bash-script/
```
<!--+- "{{execute}}"+-->

3. Run the app
```
docker run sample-app
```
<!--+- "{{execute}}"+-->

The following environment variables were set and available to buildpacks at build-time:

| Name    | Value   |  _Source_                  |
|---------|---------|----------------------------|
| `HELLO` | `WORLD` | _hard-coded inline value_  |
| `FOO`   | `BAR`   | _current environment_      |


### Using env files (`--env-file`)

The `--env-file` parameter must be a path to a file where each line is one of the following:

- `VARIABLE=VALUE`
- `VARIABLE`, where the value of `VARIABLE` will be taken from the current environment

##### Example:

1. Set an environment variable
```
export FOO=BAR
```
<!--+- "{{execute}}"+-->

2. Create an env file
```
echo -en "HELLO=WORLD\nFOO" > ./envfile
```
<!--+- "{{execute}}"+-->

3. Build the app
```
pack build sample-app \
    --env-file ./envfile \
    --builder cnbs/sample-builder:resolute \
    --buildpack  samples/buildpacks/hello-world/ \
    --buildpack samples/apps/bash-script/bash-script-buildpack/ \
    --path  samples/apps/bash-script/
```
<!--+- "{{execute}}"+-->

4. Run the app
```
docker run sample-app
```
<!--+- "{{execute}}"+-->

The following environment variables were set and available to buildpacks at build-time:

| Name    | Value   |  _Source_                  |
|---------|---------|----------------------------|
| `HELLO` | `WORLD` | _hard-coded value in file_ |
| `FOO`   | `BAR`   | _current environment_      |



> **NOTE:** Variables defined using `--env` take precedence over variables defined in `--env-file`.

### Using project descriptor
The `--descriptor` parameter must be a path to a file which follows the project.toml [schema][descriptor-schema].
Without the `--descriptor` flag, `pack build` will use the `project.toml` file in the app directory if it exists.
You can define environment variables in an `env` table in the file, and pass those into the app.

##### Example:

1. Add an environment variable to the project.toml

```
cat >> samples/apps/bash-script/project.toml <<EOL

[[io.buildpacks.build.env]]
name="HELLO"
value="WORLD"
EOL
```
<!--+- "{{execute}}"+-->

2. Build the app
```
pack build sample-app \
    --builder cnbs/sample-builder:resolute \
    --buildpack  samples/buildpacks/hello-world/ \
    --buildpack samples/apps/bash-script/bash-script-buildpack/ \
    --path  samples/apps/bash-script/
```
<!--+- "{{execute}}"+-->

3. Run the app
```
docker run sample-app
```
<!--+- "{{execute}}"+-->

The following environment variables were set and available to buildpacks at build-time:

| Name    | Value   |  _Source_                  |
|---------|---------|----------------------------|
| `HELLO` | `WORLD` | _hard-coded value in file_ |


> **NOTE:** Variables defined using `--env` or `--env-file` take precedence over variables defined in the `project.toml`.

> **NOTE:** `project.toml` can't detect environment variables (so, for instance, if one ran `export FOO=BAR` and added
>`name=FOO` to the `project.toml`, it wouldn't detect any value set for `FOO`).

[descriptor-schema]: /docs/reference/project-descriptor/
[samples]: https://github.com/buildpacks/samples