Configure Build Time Environment

+++ 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.

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, 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

2. Build the app

pack build sample-app \
    --env "HELLO=WORLD" \
    --env "FOO" \
    --builder cnbs/sample-builder:noble \
    --buildpack  samples/buildpacks/hello-world/ \
    --buildpack samples/apps/bash-script/bash-script-buildpack/ \
    --path  samples/apps/bash-script/

3. Run the app

docker run sample-app

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

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

2. Create an env file

echo -en "HELLO=WORLD\nFOO" > ./envfile

3. Build the app

pack build sample-app \
    --env-file ./envfile \
    --builder cnbs/sample-builder:noble \
    --buildpack  samples/buildpacks/hello-world/ \
    --buildpack samples/apps/bash-script/bash-script-buildpack/ \
    --path  samples/apps/bash-script/

4. Run the app

docker run sample-app

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

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. Without the --descriptor flag, pack build will use the project.toml file in the application directory if it exists. You can define environment variables in an env table in the file, and pass those into the application.

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

2. Build the app

pack build sample-app \
    --builder cnbs/sample-builder:noble \
    --buildpack  samples/buildpacks/hello-world/ \
    --buildpack samples/apps/bash-script/bash-script-buildpack/ \
    --path  samples/apps/bash-script/

3. Run the app

docker run sample-app

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

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).