User config reference

This page provides a comprehensive reference of all configuration parameters available in the user config file.

For more information about how user configuration works, see the user configuration overview.

Configuration file location

User configuration is loaded from platform-specific locations:

Platform	Primary path	Fallback path
Linux, macOS, and other Unix	$XDG_CONFIG_HOME/nextest/config.toml or ~/.config/nextest/config.toml	—
Windows	%APPDATA%\nextest\config.toml	%XDG_CONFIG_HOME%\nextest\config.toml or %HOME%\.config\nextest\config.toml

For more information about configuration hierarchy, see Configuration hierarchy.

Experimental features

0.9.123

Experimental features are configured under [experimental].

experimental.record

• Type: Boolean
• Description: Enables the record feature
• Documentation: Record, replay, and rerun
• Default: false
• Environment variable: NEXTEST_EXPERIMENTAL_RECORD=1
• Example:

  [experimental]
  record = true
  

Record configuration

0.9.123

Record configuration is specified under [record]. Recording requires both [experimental] record = true and [record] enabled = true.

For detailed information, see Record, replay, and rerun.

record.enabled

• Type: Boolean
• Description: Whether to record test runs
• Default: false
• Example:

  [record]
  enabled = true
  

record.max-output-size

• Type: String (size)
• Description: Maximum size per output file before truncation
• Default: "10MB"

record.max-records

• Type: Integer
• Description: Maximum number of recorded runs to retain
• Default: 100

record.max-total-size

• Type: String (size)
• Description: Maximum total size of all recorded runs
• Default: "1GB"

record.max-age

• Type: String (duration)
• Description: Maximum age of recorded runs before eviction
• Default: "30d"

UI configuration

UI settings are configured under [ui].

ui.show-progress

0.9.118

• Type: String
• Description: Controls how progress is displayed during test runs
• Valid values:
  • "auto": Auto-detect based on terminal capabilities
  • "none": No progress display
  • "bar": Show a progress bar with running tests
  • "counter": Show a simple test counter (e.g., "(1/10)")
  • "only": Show only the progress bar, hide successful test output
• Default: "auto"
• CLI equivalent: --show-progress
• Environment variable: NEXTEST_SHOW_PROGRESS
• Example:

  [ui]
  show-progress = "bar"
  

ui.max-progress-running

0.9.118

• Type: Integer or string
• Description: Maximum number of running tests to display in the progress bar. When more tests are running than this limit, the progress bar shows the first N tests and a summary (e.g., "... and 24 more tests running").
• Valid values:
  • Positive integer (e.g., 8): Display up to this many running tests
  • 0: Hide running tests entirely
  • "infinite": Display all running tests
• Default: 8
• CLI equivalent: --max-progress-running
• Environment variable: NEXTEST_MAX_PROGRESS_RUNNING

• Examples:

  [ui]
  # Show up to 16 running tests.
  max-progress-running = 16
  

  [ui]
  # Show all running tests.
  max-progress-running = "infinite"
  

ui.input-handler

0.9.118

• Type: Boolean
• Description: Controls whether nextest's keyboard input handler is enabled. When enabled, nextest accepts keyboard shortcuts during test runs (e.g., t to dump test information, Enter to produce a summary line).
• Valid values: true or false
• Default: true (input handler enabled)
• CLI equivalent: --no-input-handler (to disable)
• Environment variable: NEXTEST_NO_INPUT_HANDLER=1 (to disable)
• Example:

  [ui]
  # Disable keyboard input handling.
  input-handler = false
  

ui.output-indent

0.9.118

• Type: Boolean
• Description: Controls whether captured test output is indented. By default, test output produced by --failure-output and --success-output is indented for visual clarity.
• Valid values: true or false
• Default: true
• CLI equivalent: --no-output-indent (to disable)
• Environment variable: NEXTEST_NO_OUTPUT_INDENT=1 (to disable)
• Example:

  [ui]
  # Disable output indentation.
  output-indent = false
  

ui.pager

0.9.120

• Type: String, array, or table
• Description: Specifies the pager command for output that benefits from scrolling (e.g., nextest list, help output). See Pager support for details.
• Valid values:
  • String: "less -FRX" (split on whitespace)
  • Array: ["less", "-FRX"]
  • Table: { command = ["less", "-FRX"], env = { LESSCHARSET = "utf-8" } }
  • ":builtin": Use the builtin pager
• Default: { command = ["less", "-FRX"], env = { LESSCHARSET = "utf-8" } } on Unix, ":builtin" on Windows (specified via an override)
• CLI equivalent: --no-pager (to disable paging)

• Examples:

  [ui]
  # Use less with custom flags.
  pager = "less -FRX"
  

  [ui]
  # Use the builtin pager.
  pager = ":builtin"
  

  [ui]
  # Use less with environment variables.
  pager = { command = ["less", "-FRX"], env = { LESSCHARSET = "utf-8" } }
  

ui.paginate

0.9.120

• Type: String
• Description: Controls when to paginate output.
• Valid values:
  • "auto": Page supported commands if stdout is a terminal
  • "never": Never use a pager
• Default: "auto"
• CLI equivalent: --no-pager (equivalent to paginate = "never")
• Example:

  [ui]
  # Never use a pager.
  paginate = "never"
  

Builtin pager configuration

0.9.120

When pager = ":builtin" is set, the builtin pager's behavior can be customized under [ui.streampager]. See Pager support for details.

ui.streampager.interface

• Type: String
• Description: Controls how the builtin pager uses the alternate screen.
• Valid values:
  • "quit-if-one-page": Exit immediately if content fits on one page; otherwise use full screen and clear on exit
  • "full-screen-clear-output": Always use full screen mode and clear the screen on exit
  • "quit-quickly-or-clear-output": Wait briefly before entering full screen; clear on exit if entered
• Default: "quit-if-one-page"
• Example:

  [ui.streampager]
  interface = "full-screen-clear-output"
  

ui.streampager.wrapping

• Type: String
• Description: Controls text wrapping in the builtin pager.
• Valid values:
  • "none": No wrapping; allow horizontal scrolling
  • "word": Wrap at word boundaries
  • "anywhere": Wrap at any character (grapheme) boundary
• Default: "word"
• Example:

  [ui.streampager]
  wrapping = "none"
  

ui.streampager.show-ruler

• Type: Boolean
• Description: Whether to show a ruler at the bottom of the builtin pager.
• Valid values: true or false
• Default: true
• Example:

  [ui.streampager]
  show-ruler = false
  

Platform-specific overrides

0.9.120

You can customize UI settings for specific platforms using [[overrides]] sections. This is useful when different platforms need different defaults (e.g., different progress display settings).

Override structure

Platform-specific overrides

[[overrides]]
platform = "cfg(windows)"
ui.show-progress = "bar"
ui.max-progress-running = 4

Each override has a required platform filter and optional settings in the ui section. Overrides are evaluated in order. For each setting, the first matching override provides the value. If no override matches, the base [ui] section value is used.

Override filter

overrides.platform

• Type: String (target spec expression)
• Description: Platform specification for when this override applies. The expression is evaluated against the host platform (where nextest is running).
• Required: Yes
• Documentation: Specifying platforms
• Valid formats:
  • Target triple: "x86_64-unknown-linux-gnu"
  • cfg() expression: "cfg(windows)", "cfg(unix)", "cfg(target_os = \"macos\")"
• Examples:

  [[overrides]]
  platform = "cfg(windows)"
  ui.show-progress = "bar"
  
  [[overrides]]
  platform = "cfg(target_os = \"macos\")"
  ui.max-progress-running = 16
  

Overridable settings

All [ui], [ui.streampager], and [record] settings can be overridden within [[overrides]]:

• ui.show-progress
• ui.max-progress-running
• ui.input-handler
• ui.output-indent
• ui.pager
• ui.paginate
• ui.streampager.interface
• ui.streampager.wrapping
• ui.streampager.show-ruler
• record.enabled
• record.max-output-size
• record.max-records
• record.max-total-size
• record.max-age

Each setting in an override is optional. The first matching override is applied on a per-setting basis.

Example: platform-specific configuration

~/.config/nextest/config.toml

[ui]
# Base configuration for all platforms.
show-progress = "auto"
max-progress-running = 8

[[overrides]]
# Windows often has narrower terminals.
platform = "cfg(windows)"
ui.max-progress-running = 4

[[overrides]]
# macOS users might prefer a specific setting.
platform = "cfg(target_os = \"macos\")"
ui.show-progress = "bar"

Resolution order

Settings are resolved with the following precedence (highest priority first):

1. CLI arguments (e.g., --show-progress=bar)
2. Environment variables (e.g., NEXTEST_SHOW_PROGRESS=bar)
3. User overrides (first matching [[overrides]] for each setting)
4. User base config ([ui] section)
5. Built-in defaults

Default configuration

The default user configuration is:

# This is the default user config used by nextest. It is embedded in the binary
# at build time. It may be used as a template for ~/.config/nextest/config.toml.
#
# For documentation on these settings, see:
# https://nexte.st/docs/user-config/reference

[ui]
# How to show progress during test runs.
# Valid values: "auto", "none", "bar", "counter", "only"
show-progress = "auto"

# Maximum running tests to display in the progress bar.
# Valid values: an integer, or "infinite" for unlimited.
max-progress-running = 8

# Whether to enable the input handler for keyboard shortcuts during test runs.
input-handler = true

# Whether to indent captured test output for visual clarity.
output-indent = true

# Pager for supported command output.
#
# Accepts a command string ("less -FRX"), an array (["less", "-FRX"]),
# a table ({ command = ["less", "-FRX"], env = { LESSCHARSET = "utf-8" } }),
# or ":builtin" to use the builtin pager.
pager = { command = ["less", "-FRX"], env = { LESSCHARSET = "utf-8" } }

# When to paginate output.
# Valid values: "auto", "never"
paginate = "auto"

# Configuration for the builtin streampager (used when pager = ":builtin").
[ui.streampager]
# Interface mode controlling alternate screen behavior.
# Valid values: "quit-if-one-page", "full-screen-clear-output", "quit-quickly-or-clear-output"
interface = "quit-if-one-page"
# Text wrapping mode.
# Valid values: "none", "word", "anywhere"
wrapping = "word"
# Whether to show a ruler at the bottom.
show-ruler = true

# Record retention settings (for experimental record-replay feature).
[record]
# Whether recording is enabled.
# Recording only occurs when the `record` experimental feature is enabled AND
# this is set to true.
enabled = false
# Maximum number of recorded runs to keep.
max-records = 100
# Maximum total size of all recorded runs.
max-total-size = "1GB"
# Maximum age of recorded runs.
max-age = "30d"
# Maximum size of a single output (stdout/stderr) before truncation.
max-output-size = "10MB"

# Windows uses the builtin pager by default because external pagers are
# unreliable on Windows.
[[overrides]]
platform = "cfg(windows)"
ui.pager = ":builtin"