`tyro.conf`¶

The tyro.conf submodule contains helpers for attaching parsing-specific configuration metadata to types via PEP 593 runtime annotations.

Configuration markers allow you to customize generated CLI interfaces, such as to set positional arguments, suppress fields, or change boolean flag behaviors.

Markers can be applied in three ways:

They can be subscripted directly: tyro.conf.FlagConversionOff[bool]
They can be passed into typing.Annotated: Annotated[str, tyro.conf.Positional]
They can be passed into tyro.cli(): tyro.cli(Args, config=(tyro.conf.FlagConversionOff,))

Markers are applied recursively to nested structures.

These features are fully supported but should be used sparingly. Prefer using standard Python type annotations whenever possible.

See Basics for examples of using configuration markers.

Package Contents¶

Provides fine-grained control over individual CLI argument properties.

The arg() function allows you to customize how individual arguments appear and behave in the command-line interface. This provides more control than relying on the automatic argument generation.

Example:

from dataclasses import dataclass
from typing import Annotated
import tyro

@dataclass
class Config:
    # Default argument appearance
    regular_option: int = 1

    # Customized argument
    custom_option: Annotated[
        str,
        tyro.conf.arg(
            name="opt",                     # Shorter name
            help="Custom help message",     # Override docstring
            aliases=("-o", "--short-opt"),  # Alternative flags
            metavar="VALUE"                 # Display in help
        )
    ] = "default"

# Usage:
# python script.py --regular-option 5 --opt custom_value
# python script.py --regular-option 5 -o custom_value

The arg() function should be used at the root level of annotations and not nested within container types like lists.

Parameters:

name – A custom name for the argument in the CLI.
metavar – Argument placeholder shown in usage messages. The type is used by default.
help – Custom helptext for this argument. The docstring is used by default.
help_behavior_hint – Override the highlighted hint text that follows the helptext. This is typically used for hints like “(default: XXX)” or “(optional)”. You can provide either a string or a lambda function that takes a formatted default value as input.
aliases – Alternative flag names for this argument. All strings must start with a hyphen (-). Aliases are not prefixed in nested structures and are not supported for positional arguments.
prefix_name – Controls whether to prefix the argument name based on its position in a nested structure. Arguments are prefixed by default.
constructor – A custom constructor type or function to use in place of the argument’s type for parsing. See tyro.constructors for more details.
constructor_factory – A function that returns a constructor type for parsing. This cannot be used together with the constructor parameter.
default – Default value for the argument. This will be used only if the field does not have a default value. The field default takes precedence.

Returns:

A configuration object that should be attached to a type using Annotated[].

tyro.conf.subcommand(name: str | None = None, *, default: Any = MISSING_NONPROP, description: str | None = None, prefix_name: bool = True, constructor: None = None, constructor_factory: Callable[[], type | Callable[Ellipsis, Any]] | None = None) → Any[source]¶

tyro.conf.subcommand(name: str | None = None, *, default: Any = MISSING_NONPROP, description: str | None = None, prefix_name: bool = True, constructor: type | Callable[Ellipsis, Any] | None = None, constructor_factory: None = None) → Any

Configure subcommand behavior for Union types in the CLI.

When tyro encounters a Union type over structures, it creates subcommands in the CLI. The subcommand() function allows you to customize the appearance and behavior of these subcommands.

Example:

from dataclasses import dataclass
from typing import Annotated, Union
import tyro

@dataclass
class TrainConfig:
    learning_rate: float = 0.01

@dataclass
class EvalConfig:
    checkpoint_path: str

@dataclass
class MainConfig:
    # Customized subcommands:
    mode: Union[
        Annotated[TrainConfig, tyro.conf.subcommand("train")],
        Annotated[EvalConfig, tyro.conf.subcommand("evaluate")]
    ]

# CLI usage: python script.py mode:train --mode.learning-rate 0.02

If a default value is provided both via subcommand(default=…) and in the field definition itself (field = default), the field default will take precedence.

Parameters:

name – Custom name for the subcommand in the CLI.
default – Default instance to use for this subcommand.
description – Custom helptext for this subcommand.
prefix_name – Whether to include the parent field name as a prefix in the subcommand name (default: True).
constructor – Custom constructor type or function for parsing arguments.
constructor_factory – Function that returns a constructor type for parsing arguments (cannot be used with constructor).

Returns:

A configuration object that should be attached to a type using Annotated[].

tyro.conf.AvoidSubcommands¶

Avoid creating subcommands for union types that have a default value.

When a union type has a default value, tyro creates a subcommand interface. With AvoidSubcommands, tyro will use the default value and not create subcommands, simplifying the CLI interface (but making it less expressive).

Example:

# Without AvoidSubcommands
@dataclass
class Config:
    mode: Union[ClassA, ClassB] = ClassA()
    # CLI would have subcommands: python script.py mode:class-a ... or mode:class-b ...

# With AvoidSubcommands
@dataclass
class Config:
    mode: AvoidSubcommands[Union[ClassA, ClassB]] = ClassA()
    # CLI would not have subcommands, would use ClassA() as default

This can be applied to specific union fields or globally with the config parameter.

tyro.conf.ConsolidateSubcommandArgs¶

Consolidate arguments for nested subcommands to make CLI less position-sensitive.

By default, tyro generates CLI interfaces where arguments apply to the directly preceding subcommand, which creates position-dependent behavior:

# Default behavior - position matters
python x.py {--root options} s1 {--s1 options} s2 {--s2 options}

With ConsolidateSubcommandArgs, all arguments are moved to the end, after all subcommands:

# With ConsolidateSubcommandArgs - all options at the end
python x.py s1 s2 {--root, s1, and s2 options}

This makes the interface more robust to argument reordering, but has a tradeoff: if root options are required (have no defaults), all subcommands must be specified before providing those required arguments.

Example:

tyro.cli(NestedConfig, config=(tyro.conf.ConsolidateSubcommandArgs,))

tyro.conf.EnumChoicesFromValues¶

Use enum values instead of enum names for command-line choices.

By default, tyro uses enum member names as the choices shown in the CLI. With EnumChoicesFromValues, the enum values are used as choices instead.

Example:

import enum
from dataclasses import dataclass
import tyro

class OutputFormat(enum.StrEnum):
    JSON = enum.auto()      # value is "json"
    PRETTY = enum.auto()    # value is "pretty"
    RICH = enum.auto()      # value is "rich"
    TOML = enum.auto()      # value is "toml"

@dataclass
class Config:
    # Default behavior: choices would be JSON, PRETTY, RICH, TOML
    format: OutputFormat = OutputFormat.PRETTY

    # With EnumChoicesFromValues: choices are json, pretty, rich, toml
    alt_format: EnumChoicesFromValues[OutputFormat] = OutputFormat.PRETTY

This is useful with auto-generated enum values like those in enum.StrEnum, where the values may be more user-friendly than the internal names.

When EnumChoicesFromValues is used, enum aliases aren’t considered. The first enum member with a matching value will be selected.

tyro.conf.Fixed¶

Mark a field as fixed, preventing it from being modified through the CLI.

When a field is marked as Fixed, tyro will use the default value and will not create a CLI option for it. This is useful for fields that should not be configurable via command line arguments.

Example:

@dataclass
class Config:
    input_path: str
    debug_mode: Fixed[bool] = False  # Cannot be changed via CLI
    version: Fixed[str] = "1.0.0"    # Cannot be changed via CLI

Fields that aren’t support by tyro but have defaults will be automatically marked as fixed.

tyro.conf.FlagConversionOff¶

Disable automatic flag-style conversion for boolean fields.

By default, boolean fields with default values are converted to flags that can be enabled or disabled with command-line options. With FlagConversionOff, the boolean fields will expect an explicit True or False value.

Example:

# Default behavior (with flag conversion)
debug: bool = False
# Usage: python script.py --debug      # Sets to True
#        python script.py --no-debug   # Sets to False

# With FlagConversionOff
debug: FlagConversionOff[bool] = False
# Usage: python script.py --debug True  # Explicit value required
#        python script.py --debug False

This marker can be applied to specific boolean fields or globally using the config parameter.

tyro.conf.FlagCreatePairsOff¶

Disable creation of matching flag pairs for boolean types.

By default, tyro creates both positive and negative flags for boolean values (like --flag and --no-flag). With FlagCreatePairsOff, only one flag will be created:

--flag if the default is False
--no-flag if the default is True

Example:

# Default behavior (with flag pairs)
debug: bool = False
# Usage: python script.py --debug      # Sets to True
#        python script.py --no-debug   # Sets to False

# With FlagCreatePairsOff
debug: FlagCreatePairsOff[bool] = False
# Usage: python script.py --debug      # Sets to True
#        (--no-debug flag is not created)

This can make the helptext less cluttered but is less robust if default values change.

tyro.conf.HelptextFromCommentsOff¶

Disable automatic helptext generation from code comments.

By default, tyro extracts helptext from comments in the source code: - Comments before a field definition are used as helptext - Inline comments following a field definition are used as helptext

Example:

@dataclass
class Config:
    # This comment becomes helptext for input_file
    input_file: str

    output_file: str  # This inline comment becomes helptext for output_file

If you have code with many organizational or implementation comments that shouldn’t appear in the CLI help, this automatic extraction might be unhelpful. This marker disables comment extraction while preserving docstring extraction.

Example:

tyro.cli(Config, config=(tyro.conf.HelptextFromCommentsOff,))

Triple-quoted docstrings on fields are still used for helptext even when this marker is applied.

tyro.conf.OmitArgPrefixes¶

Simplify argument names by removing parent field prefixes from flags.

By default, tyro creates namespaced flags for nested structures (like --parent.child.option). With OmitArgPrefixes, the prefixes are omitted, resulting in shorter argument names.

Example:

@dataclass
class NestedConfig:
    option: str = "value"

@dataclass
class Config:
    nested: OmitArgPrefixes[NestedConfig]

# Default CLI (with prefixes):
# python script.py --nested.option value

# With OmitArgPrefixes:
# python script.py --option value

This can simplify command lines but may cause name conflicts if multiple nested structures have fields with the same name.

tyro.conf.OmitSubcommandPrefixes¶

Simplify subcommand names by removing parent field prefixes from subcommands.

By default, tyro uses prefixes to create namespaced subcommands and arguments. With OmitSubcommandPrefixes, subcommand prefixes are omitted, making CLI commands shorter.

Example:

@dataclass
class Config:
    mode: Union[ProcessorA, ProcessorB]

# Default CLI (with prefixes):
# python script.py mode:processor-a --mode.option value

# With OmitSubcommandPrefixes:
# python script.py processor-a --option value

This is useful for deeply nested structures where the fully prefixed arguments would become unwieldy.

tyro.conf.Positional¶

Mark a parameter to be parsed as a positional argument rather than a keyword argument.

Example:

@dataclass
class Args:
    input_file: Positional[str]  # Will be a positional arg
    output_file: str  # Will be a keyword arg (--output-file)

With this configuration, the CLI would accept: python script.py input.txt --output-file output.txt

tyro.conf.PositionalRequiredArgs¶

Make all required arguments (those without default values) positional.

This marker applies to an entire interface when passed to the config parameter of tyro.cli().

Example:

@dataclass
class Args:
    input_file: str  # No default, will be positional
    output_file: str = "output.txt"  # Has default, will be a keyword arg

args = tyro.cli(Args, config=(tyro.conf.PositionalRequiredArgs,))

tyro.conf.Suppress¶

Remove a field from the CLI interface and helptext.

Unlike Fixed, which shows the field in the helptext but prevents modification, Suppress hides the field from both the CLI and the helptext.

Example:

@dataclass
class Config:
    input_path: str
    # Internal fields that users don't need to see
    _cached_data: Suppress[dict] = dataclasses.field(default_factory=dict)
    _debug_level: Suppress[int] = 0

tyro.conf.SuppressFixed¶

Hide fields that are marked as Fixed from the helptext.

This marker can be applied globally to hide all fixed fields from the helptext, making the interface cleaner by showing only fields that can be modified via CLI.

Example:

tyro.cli(Config, config=(tyro.conf.SuppressFixed,))

tyro.conf.UseAppendAction¶

Enable specifying list elements through repeated flag usage rather than space-separated values.

By default, tyro expects list elements to be provided as space-separated values after a single flag. With UseAppendAction, each element is provided by repeating the flag multiple times.

Example:

@dataclass
class Config:
    # Default list behavior
    numbers: list[int]
    # With UseAppendAction
    tags: UseAppendAction[list[str]]

# Default list usage:
# python script.py --numbers 1 2 3

# UseAppendAction usage:
# python script.py --tags red --tags green --tags blue

This provides two benefits: 1. More intuitive for some users who prefer repeating arguments 2. Enables support for nested lists like list[list[int]] that would otherwise be ambiguous

tyro.conf.UseCounterAction¶

Create a counter-style flag that increments an integer each time it appears.

This marker converts an integer parameter into a counter where each occurrence of the flag increases the value by 1, similar to common CLI tools like -v, -vv, -vvv for verbosity.

Example:

@dataclass
class Config:
    verbose: UseCounterAction[int] = 0

# Usage:
# python script.py            # verbose = 0
# python script.py --verbose  # verbose = 1
# python script.py --verbose --verbose  # verbose = 2
# python script.py --verbose --verbose --verbose  # verbose = 3

This is useful for verbosity levels or similar numeric settings where repeated flags are more intuitive than explicit values.

tyro.conf.configure(*markers: Marker) → Callable[[CallableType], CallableType][source]¶

Decorator for applying configuration options.

Warning

We recommend avoiding this function if possible. For global flags, prefer passing config= to tyro.cli() instead.

Consider using the config= argument of tyro.cli() instead, which takes the same config marker objects as inputs.

Configuration markers are implemented via typing.Annotated and straightforward to apply to types, for example:

field: tyro.conf.FlagConversionOff[bool]

This decorator makes markers applicable to general functions as well:

# Recursively apply FlagConversionOff to all fields in `main()`.
@tyro.conf.configure(tyro.conf.FlagConversionOff)
def main(field: bool) -> None:
    ...

Parameters:: markers (Marker) – Options to apply.
Return type:: Callable[[CallableType], CallableType]

tyro.conf¶

Package Contents¶

`tyro.conf`¶