Context formatting¶

You can populate configuration with the values of certain supported fields using the syntax of Python's format strings. Each field interprets the modifier part after the colon differently, if at all.

Global fields¶

Any configuration that declares support for context formatting will always support these fields.

Paths¶

Field	Description
`root`	The root project directory
`home`	The user's home directory

All paths support the following modifiers:

Modifier	Description
`uri`	The normalized absolute URI path prefixed by `file:`
`real`	The path with all symbolic links resolved
`parent`	The parent of the preceding path

Tip

The parent modifier can be chained and may be combined with either the uri or real modifier, with the latter placed at the end. For example:

pyproject.toml hatch.toml


[tool.hatch.envs.test]
dependencies = [
    "example-project @ {root:parent:parent:uri}/example-project",
]


[envs.test]
dependencies = [
    "example-project @ {root:parent:parent:uri}/example-project",
]

System separators¶

Field	Description
`/`	`\` on Windows, `/` otherwise
`;`	`;` on Windows, `:` otherwise

Environment variables¶

The env field and its modifier allow you to select the value of an environment variable. If the environment variable is not set, you must specify a default value as an additional modifier e.g. {env:PATH:DEFAULT}.

Field nesting¶

You can insert fields within others. For example, if you wanted a script that displays the value of the environment variable FOO, with a fallback to the environment variable BAR, with its own fallback to the user's home directory, you could do the following:

pyproject.toml hatch.toml


[tool.hatch.envs.test.scripts]
display = "echo {env:FOO:{env:BAR:{home}}}"


[envs.test.scripts]
display = "echo {env:FOO:{env:BAR:{home}}}"