Install & Compatibility
Where this runs
tested against v1.5.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.9100 runs
installs and imports cleanly · install 0.0s · import 0.184s · 34.1MB
glibcpy 3.10–3.9100 runs
installs and imports cleanly · install 2.9s · import 0.165s · 35MB
33MB installed
● package 33MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
use_yaml_config
✓ from typer_config import use_yaml_config
use_json_config
✓ from typer_config import use_json_config
use_toml_config
✓ from typer_config import use_toml_config
use_dotenv_config
✓ from typer_config import use_dotenv_config
use_config
✓ from typer_config import use_config
This quickstart demonstrates how to integrate `typer-config` using the `@use_yaml_config()` decorator. Create a `config.yml` file in the same directory with `name: Alice` and `age: 30`. Run the script with `python your_script.py` or `python your_script.py --config config.yml`. The parameters `name` and `age` will be populated from the config file, which can be overridden by command-line arguments.
import typer
from typer_config import use_yaml_config
from typing import Optional
app = typer.Typer()
@app.command()
@use_yaml_config()
def main(
name: str = "World",
age: Optional[int] = None,
config_file: Optional[str] = typer.Option(None, hidden=True) # Added for registry example clarity
):
"""A simple CLI app using a YAML config file."""
print(f"Hello, {name}!")
if age:
print(f"You are {age} years old.")
if config_file:
print(f"Using config file: {config_file}")
if __name__ == "__main__":
# Example config.yml content (create this file for testing):
# name: Alice
# age: 30
app()
Debug
Known issues
gotchaWhen using configuration decorators like `@use_yaml_config()`, they must be placed *after* the `@app.command()` decorator on the function definition. Incorrect placement will prevent the configuration from being loaded and applied correctly.fixEnsure the `@use_yaml_config()` (or similar) decorator is applied beneath `@app.command()`.
affects: All versions
gotchaWhen providing a custom loader function to `@use_config()`, ensure it gracefully handles cases where no config file path is provided or the file doesn't exist. Otherwise, the CLI might raise an error during `--help` output or when the `--config` option is omitted, leading to a poor user experience.fixImplement a conditional check within your custom loader function to return an empty dictionary or handle `None` for the config path gracefully if no file is meant to be loaded.
affects: All versions, particularly with custom loaders.
gotchaOptional dependencies for specific config formats (e.g., `PyYAML` for YAML) are not automatically installed with `pip install typer-config`. If you intend to use a particular format, you must install the corresponding optional dependencies using `pip install typer-config[format_name]` or `typer-config[all]`.fixInstall `typer-config` with the required extras, e.g., `pip install typer-config[yaml]` for YAML support.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'typer_config'
The `typer-config` library has not been installed in your current Python environment.
fixRun `pip install typer-config` to add the library to your project.
typer_config.errors.ConfigFileNotFoundError: Configuration file at 'config.yaml' not found.
The Typer-Config library could not find the specified configuration file at the given path or in default search locations.
fixEnsure the configuration file exists at the specified path (e.g., passed via `--config` option or `TYPER_CONFIG_FILE` environment variable), or create it.
yaml.YAMLError: while parsing a block mapping
The YAML configuration file contains syntax errors or is malformed, preventing it from being parsed correctly.
fixReview and correct the syntax of your YAML configuration file (e.g., indentation, colon usage, valid key-value pairs).
Upgrade
Version history
1.5.1latest on PyPI · released Mar 1, 2026
Audit
Dependencies
typerrequiredCore dependency as typer-config extends Typer CLI functionality.
PyYAMLoptionalRequired for YAML configuration file support.
tomloptionalRequired for TOML configuration file support.
python-dotenvoptionalRequired for Dotenv configuration file support.