Skip to content

Profiles

Profiles group settings for different runs, such as local development and CI.

Configuration lives in karva.toml (or the [tool.karva] table in pyproject.toml); the path can be overridden with --config-file.

Profiles

To use multiple sets of configuration, define [profile.<name>] sections in karva.toml:

TOML
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
[profile.default.test]
test-function-prefix = "test"
retry = 1

[profile.ci.test]
retry = 5
no-tests = "fail"

[profile.ci.terminal]
output-format = "concise"

The same configuration in pyproject.toml lives under [tool.karva.profile.<name>].

A profile is selected at runtime with --profile <name> (or -P <name>), or by setting the KARVA_PROFILE environment variable. If neither is set, the implicit default profile is used.

All profile-scoped configuration documented in Configuration — env, src, terminal, test, coverage, junit, and overrides — may appear inside a profile. These settings are not accepted without profile.<name>.

Reserved profile names

Avoid custom profile names that begin with default-. The default- prefix is reserved for built-in profiles that Karva may add in the future.

Profile inheritance

A non-default profile is layered on top of [profile.default]: any field the named profile does not set falls back to the value from default, which in turn falls back to Karva's built-in defaults. Concretely, given:

TOML
1
2
3
4
5
6
[profile.default.test]
test-function-prefix = "test"
retry = 1

[profile.ci.test]
retry = 5

uv run karva test --profile ci runs with test-function-prefix = "test" (inherited from default) and retry = 5 (overridden by ci).

Hierarchical configuration

When resolving a setting for a run, Karva checks the following sources from highest to lowest priority. The first source that defines the field wins.

  1. Command-line arguments (e.g. --retry 3, --no-fail-fast).
  2. Environment variables (e.g. KARVA_PROFILE, KARVA_NO_TESTS).
  3. The selected profile, when not default ([profile.<name>]).
  4. The default profile ([profile.default]).
  5. Built-in defaults compiled into Karva.

Selecting a profile that is not defined in the configuration produces an error that lists the profiles that are available.

Inspecting the resolved configuration

Use uv run karva show-config to print the resolved configuration as TOML:

Bash
1
2
uv run karva show-config              # default profile
uv run karva show-config --profile ci

See also

  • Configuration — reference for every supported field.
  • CLI — every flag, including --profile and --config-file.