# How to Configure Verbosity, Output Streams, and Color Modes in Catch2

> Master Catch2 output configuration. Learn to control verbosity, direct output streams, and set color modes for detailed test reporting. Read now!

- Repository: [Catch Org/Catch2](https://github.com/catchorg/Catch2)
- Tags: how-to-guide
- Published: 2026-07-29

---

**You configure Catch2’s output behavior through global command-line flags for verbosity and colour modes, while per-reporter settings—including output file redirection—are specified via the `::out=` and `::colour-mode=` syntax in reporter specifications.**

The catchorg/Catch2 testing framework separates output control into global configuration values stored in the `Config` class and per-reporter overrides defined in `ProcessedReporterSpec` objects. Understanding how to configure verbosity, output streams, and color modes in Catch2 requires examining the `IConfig` interface declaration, the command-line parser implementation, and the reporter specification builder.

## Configuration Architecture

Catch2 defines two primary output control mechanisms in [`src/catch2/interfaces/catch_interfaces_config.hpp`](https://github.com/catchorg/Catch2/blob/main/src/catch2/interfaces/catch_interfaces_config.hpp): **verbosity** determines detail levels, while **colour mode** selects the coloring implementation.

### Verbosity Levels

The `enum class Verbosity` at lines 20-24 declares three levels that control how much detail reporters emit:

- `quiet` — Shows only failures and summary statistics
- `normal` — Standard test results with failure details (default)
- `high` — Lists all tests including successful ones with full expressions

The framework stores this value in `Config::m_data.verbosity` and exposes it through `IConfig::verbosity()`, implemented in [`src/catch2/catch_config.cpp`](https://github.com/catchorg/Catch2/blob/main/src/catch2/catch_config.cpp). The parser in [`src/catch2/internal/catch_commandline.cpp`](https://github.com/catchorg/Catch2/blob/main/src/catch2/internal/catch_commandline.cpp) (lines 124-131) maps the `--verbosity` flag arguments to these enum values.

### Colour Modes

The `enum class ColourMode` at lines 46-54 specifies the coloring backend:

- `ansi` — Standard ANSI escape sequences for terminal colors
- `win32` — Windows Console API specific calls
- `none` — Disables all color output
- `PlatformDefault` — Automatically selects based on system capabilities (default)

The global default lives in `Config::m_data.defaultColourMode`, accessible via `IConfig::defaultColourMode()`. During reporter construction, `makeColourImpl` in [`catch_reporter_helpers.cpp`](https://github.com/catchorg/Catch2/blob/main/catch_reporter_helpers.cpp) instantiates the concrete implementation based on these settings.

## Global Command-Line Configuration

Set framework-wide defaults using these flags processed by [`catch_commandline.cpp`](https://github.com/catchorg/Catch2/blob/main/catch_commandline.cpp):

**`--verbosity <quiet|normal|high>`** — Controls the global detail level stored in `Config::m_data.verbosity`.

**`--colour-mode <ansi|win32|none|default>`** — Sets the global colour implementation, replacing the legacy `--colour` flag (Catch2 3.0.1+).

```bash

# Maximum detail with forced ANSI colors

./my_tests --verbosity high --colour-mode ansi

```

```bash

# Minimal output without colors

./my_tests --verbosity quiet --colour-mode none

```

## Per-Reporter Output Streams and Colour Overrides

Redirect output destinations and override color modes for individual reporters using the specification syntax parsed in [`src/catch2/internal/catch_reporter_spec_parser.cpp`](https://github.com/catchorg/Catch2/blob/main/src/catch2/internal/catch_reporter_spec_parser.cpp) (lines 41-47). The format is:

```

--reporter <name>::out=<file>::colour-mode=<mode>

```

The `Config` constructor in [`src/catch2/catch_config.cpp`](https://github.com/catchorg/Catch2/blob/main/src/catch2/catch_config.cpp) (lines 55-60) builds `ProcessedReporterSpec` objects from these strings, allowing per-reporter settings to override global defaults.

```bash

# Console to stdout with ANSI colors, JUnit XML to file without colors

./my_tests \
  --reporter console::out=-::colour-mode=ansi \
  --reporter junit::out=results.xml::colour-mode=none

```

In this example, `-` represents stdout, while [`results.xml`](https://github.com/catchorg/Catch2/blob/main/results.xml) receives the JUnit XML output. The colour mode for each reporter is stored separately in its `ProcessedReporterSpec`, decoupling the console coloring from the XML file content.

## Configuration File Defaults

Catch2 reads a `.catch2` file in the project root directory to establish baseline settings before applying command-line overrides:

```ini

# .catch2

verbosity = high
colour-mode = ansi

```

When present, these values populate `Config::m_data` before CLI parsing occurs, allowing you to commit project-specific defaults to version control while retaining runtime flexibility.

## Implementation Reference

These source files control the configuration lifecycle:

- **[`src/catch2/interfaces/catch_interfaces_config.hpp`](https://github.com/catchorg/Catch2/blob/main/src/catch2/interfaces/catch_interfaces_config.hpp)** — Declares `Verbosity` (lines 20-24) and `ColourMode` (lines 46-54) enums
- **[`src/catch2/internal/catch_commandline.cpp`](https://github.com/catchorg/Catch2/blob/main/src/catch2/internal/catch_commandline.cpp)** — Parses `--verbosity` (lines 124-131) and `--colour-mode` flags
- **[`src/catch2/internal/catch_reporter_spec_parser.cpp`](https://github.com/catchorg/Catch2/blob/main/src/catch2/internal/catch_reporter_spec_parser.cpp)** — Extracts `out` and `colour-mode` keys from reporter specs (lines 41-47)
- **[`src/catch2/catch_config.cpp`](https://github.com/catchorg/Catch2/blob/main/src/catch2/catch_config.cpp)** — Constructs `ProcessedReporterSpec` and applies overrides (lines 55-60)
- **[`src/catch2/reporters/catch_reporter_helpers.cpp`](https://github.com/catchorg/Catch2/blob/main/src/catch2/reporters/catch_reporter_helpers.cpp)** — Implements `makeColourImpl` for runtime color instantiation

## Summary

Catch2’s output configuration follows this structural pattern:

- **Verbosity** is a global suggestion (quiet/normal/high) stored in `Config::m_data.verbosity` that reporters may interpret according to their capabilities
- **Colour modes** (ansi/win32/none/default) are defined in [`catch_interfaces_config.hpp`](https://github.com/catchorg/Catch2/blob/main/catch_interfaces_config.hpp) and instantiated via `makeColourImpl` based on `IConfig::defaultColourMode()`
- **Output streams** are configured per-reporter using `::out=<file>` syntax, with `-` indicating stdout, processed by [`catch_reporter_spec_parser.cpp`](https://github.com/catchorg/Catch2/blob/main/catch_reporter_spec_parser.cpp)
- **Per-reporter overrides** use the `::colour-mode=` syntax, stored in `ProcessedReporterSpec`, and applied in `Config`’s constructor at lines 55-60 of [`catch_config.cpp`](https://github.com/catchorg/Catch2/blob/main/catch_config.cpp)

## Frequently Asked Questions

### How do I disable colored output entirely in Catch2?

Use the `--colour-mode none` flag for global disable, or specify `::colour-mode=none` for specific reporters. According to [`catch_interfaces_config.hpp`](https://github.com/catchorg/Catch2/blob/main/catch_interfaces_config.hpp), this selects the `none` enum value, which `makeColourImpl` in [`catch_reporter_helpers.cpp`](https://github.com/catchorg/Catch2/blob/main/catch_reporter_helpers.cpp) handles by returning a null color implementation that suppresses all escape codes.

### Can different reporters use different verbosity levels?

No, verbosity is strictly a global setting stored in `Config::m_data.verbosity` and accessed via `IConfig::verbosity()`. While all reporters receive this value during initialization (as seen in [`catch_config.cpp`](https://github.com/catchorg/Catch2/blob/main/catch_config.cpp)), each reporter implementation independently decides how to honor the setting. Console reporters respect all three levels, while structured reporters like JUnit XML typically ignore verbosity since their schema is fixed.

### Why does Catch2 use "colour" instead of "color" in its API?

The framework maintains British spelling conventions throughout its codebase and user interface. The `--colour-mode` flag processed in [`catch_commandline.cpp`](https://github.com/catchorg/Catch2/blob/main/catch_commandline.cpp) and the `ColourMode` enum defined in [`catch_interfaces_config.hpp`](https://github.com/catchorg/Catch2/blob/main/catch_interfaces_config.hpp) consistently use the "colour" spelling. You must use this exact spelling; the parser does not accept "color" variants.

### Where does Catch2 store the output file configuration for reporters?

Per-reporter output streams are stored in `ProcessedReporterSpec` structures created in [`src/catch2/catch_config.cpp`](https://github.com/catchorg/Catch2/blob/main/src/catch2/catch_config.cpp) (lines 55-60). When you specify `::out=filename`, the reporter spec parser in [`catch_reporter_spec_parser.cpp`](https://github.com/catchorg/Catch2/blob/main/catch_reporter_spec_parser.cpp) extracts this value, and the `Config` constructor associates it with the specific reporter instance, directing that reporter’s output to the specified file descriptor instead of the default stdout.