Skip to main content
This guide explains the project.toml file used with Cloud Native Buildpacks. The file centralizes build configuration for an application repository: you can set the default builder image, control which files are included or excluded from the build context, declare which buildpacks should run, and specify build-time environment variables. Below is a minimal example project.toml, followed by a field-by-field walkthrough.
Always verify the schema-version against the Buildpacks project configuration documentation (https://buildpacks.io/docs/reference/config/project/) or your platform documentation to ensure you use the correct schema for your tooling.
Explanation of the main fields (in the order shown above):
  • [project]
    • schema-version: Specifies the project file schema version. Use the correct schema for your tooling and Buildpacks implementation; different pack/buildpack versions may require different schema versions. See the project configuration docs for supported versions.
    • id: Machine-readable identifier for the project (commonly reverse-DNS style, e.g., io.example.myapp).
    • name: Human-friendly application name shown in UI or logs.
    • version: Application version (semantic versioning recommended).
  • [io.buildpacks]
    • builder: Default builder image for the repository (for example, gcr.io/buildpacks/builder:google-22). When present, pack build will use this builder unless you override it with --builder.
    • exclude: Array of file globs to exclude from the build context (behaves like .dockerignore). Typical entries: node_modules, .env, test folders, or any large files you don’t want copied into the image context. By default, pack copies all files except those matching exclude.
    • include: Optional array of file paths or globs to explicitly include in the build context. Use this to ensure specific files are added even if defaults or other ignore rules would omit them.
  • [[io.buildpacks.group]]
    • Lists buildpacks (or buildpack URIs) that form the buildpack group for this project. The group controls which buildpacks are considered and in which order they are applied during a build.
  • [[io.buildpacks.build.env]]
    • name and value: Define build-time environment variables. These variables are provided to buildpacks during execution and affect the build process; they are not necessarily present at runtime unless a buildpack explicitly forwards them into the launch environment.
Summary table Common usage patterns and tips
  • Use builder to standardize builds across CI and local development so contributors don’t need to pass --builder every time. You can still override from the CLI: pack build --builder <BUILDER_IMAGE>.
  • Use exclude to shrink the build context and speed up builds—exclude node_modules, local SQLite files, or large test assets.
  • If you need to include a file that would otherwise be excluded, add it to include.
  • Define a group to pin specific buildpacks or to ensure an ordered set of buildpacks executes.
  • Put sensitive or runtime-only secrets in a secure secrets store (CI secrets or runtime environment) rather than project.toml. [[io.buildpacks.build.env]] is visible in the repo and is intended for non-sensitive build-time variables.
Example: building with pack
  • Default builder from project.toml:
    • pack build my-app
  • Override builder on the command line:
    • pack build my-app --builder gcr.io/my/custom-builder:latest
References Use project.toml to centralize builder selection, control the build context, declare buildpacks, and provide build-specific environment variables—reducing the need to supply repeated flags on the command line and making builds repeatable across environments.

Watch Video