Skip to content

Config Overview

Foundry's configuration system allows you to configure its tools.

Profiles

Configuration can be arbitrarily namespaced into profiles. The default profile is named default, and all other profiles inherit values from this profile. Profiles are defined in the profile map.

To add a profile named local, you would add:

[profile.local]

You can select the profile to use by setting the FOUNDRY_PROFILE environment variable.

Global configuration

You can create a foundry.toml file in ~/.foundry folder to configure Foundry globally.

Configuration file discovery

Foundry searches for a foundry.toml starting at the current working directory. If not found, it checks parent directories until the file is found or the root is reached. The global ~/.foundry/foundry.toml is also checked.

You can override this behavior by setting the FOUNDRY_CONFIG environment variable to an absolute or relative path to a config file:

FOUNDRY_CONFIG=./custom-config.toml forge build

If the path is absolute, it is used directly. If relative, the search behavior described above applies.

Configuration precedence

When resolving configuration values, Foundry considers the following sources in ascending priority order (later sources override earlier ones):

  1. Default values
  2. foundry.toml (or the file specified by FOUNDRY_CONFIG)
  3. Environment variables prefixed with FOUNDRY_ or DAPP_

To view the fully resolved configuration, run:

forge config

Environment variables

Configuration can be overridden with FOUNDRY_ and DAPP_ prefixed environment variables.

Exceptions are:

  • FOUNDRY_FFI, DAPP_FFI, DAPP_TEST_FFI
  • FOUNDRY_PROFILE
  • FOUNDRY_REMAPPINGS, DAPP_REMAPPINGS
  • FOUNDRY_LIBRARIES, DAPP_LIBRARIES
  • FOUNDRY_FS_PERMISSIONS, DAPP_FS_PERMISSIONS, DAPP_TEST_FS_PERMISSIONS
  • DAPP_TEST_CACHE
  • DAPP_TEST_FUZZ_RUNS
  • DAPP_TEST_FUZZ_DEPTH

Configuration format

Configuration files are written in the TOML format, with simple key-value pairs inside of sections.

This page describes each configuration key in detail. To see the default values, either refer to the specific key in this document, or see the default config.

Configuration keys

This section documents all configuration keys. All configuration keys must live under a profile, such as default.