{"library":"configargparse","title":"ConfigArgParse","description":"ConfigArgParse is a drop-in replacement for Python's standard `argparse` module, enhancing it with the ability to load configuration options from command-line arguments, environment variables, and configuration files (INI, YAML, TOML formats). It offers a unified API to define, document, and parse settings from multiple sources with a clear precedence order (command line > environment variables > config file values > defaults). The library is actively maintained, with its current version being 1.7.5.","status":"active","version":"1.7.5","language":"en","source_language":"en","source_url":"https://github.com/bw2/ConfigArgParse","tags":["configuration","argparse","CLI","environment variables","config files","INI","YAML","TOML"],"install":[{"cmd":"pip install configargparse","lang":"bash","label":"Standard Installation"},{"cmd":"pip install configargparse[yaml]","lang":"bash","label":"With YAML support"},{"cmd":"pip install configargparse toml","lang":"bash","label":"With TOML support (requires `toml` package)"}],"dependencies":[{"reason":"Required for YAML config file parsing (`YAMLConfigFileParser`).","package":"PyYAML","optional":true},{"reason":"Required for TOML config file parsing (`TomlConfigParser`). (Note: Python 3.11+ includes `tomllib` which `configargparse` can use natively, but for older Python or explicit serialization, `toml` package is needed for full functionality).","package":"toml","optional":true}],"imports":[{"note":"While `configargparse` is the module, its primary class `ArgumentParser` is typically imported directly. The alias `ArgParser` is also available.","wrong":"import configargparse.ArgumentParser","symbol":"ArgumentParser","correct":"from configargparse import ArgumentParser"}],"quickstart":{"code":"import configargparse\nimport os\n\n# Simulate an environment variable\nos.environ['MYAPP_HOST'] = 'localhost'\n\n# Create a dummy config file\nconfig_content = \"\"\"\nhost = 127.0.0.1\nport = 8080\ndebug = false\n\"\"\"\nwith open('my_config.ini', 'w') as f:\n    f.write(config_content)\n\n# Initialize the parser\np = configargparse.ArgumentParser(\n    default_config_files=['./my_config.ini'],\n    auto_env_var_prefix='MYAPP_'\n)\n\n# Add arguments\np.add('--host', help='Host address')\np.add('--port', type=int, help='Port number')\np.add('--debug', action='store_true', help='Enable debug mode')\np.add('-c', '--config', is_config_file_arg=True, help='Path to config file')\n\n# Parse arguments (simulate command line: --port 9000)\n# `parse_args` can take a list of args, e.g., ['--port', '9000']\n# For this example, we'll let it parse from system args (or defaults/env/config)\n# If running as a script, try: python your_script.py --port 9000\n# You can also set MYAPP_PORT=9001 in your shell before running.\n# For the demo, let's explicitly provide some command-line args.\nargs = p.parse_args(['--port', '9002'])\n\nprint(f\"Host: {args.host} (from config file, overridden by env var if present) \")\nprint(f\"Port: {args.port} (command line > env var > config > default)\")\nprint(f\"Debug: {args.debug} (from config file)\")\n\n# Cleanup (optional)\nos.remove('my_config.ini')\ndel os.environ['MYAPP_HOST'] # Clean up the simulated env var\n\n# Expected precedence: command line > environment variables > config file values > defaults\n# In this example:\n# - Host: 'localhost' (from MYAPP_HOST env var, overrides 127.0.0.1 in config)\n# - Port: 9002 (from explicit command line, overrides 8080 and any MYAPP_PORT)\n# - Debug: False (from config file 'debug=false' which becomes --debug false; action='store_true' needs --debug to be present for True)\n# Actually, `debug = false` in INI for `action='store_true'` will effectively NOT set the flag, resulting in False. If you want true, it should be `debug=true` or just `debug`. \n# Let's verify debug: `debug = false` in INI would mean the flag `--debug` is NOT present, so `args.debug` defaults to `False` for `action='store_true'`. If `debug=true` it would be `True`.","lang":"python","description":"This quickstart demonstrates how to define arguments and have them automatically loaded from a default config file and environment variables, with command-line arguments taking the highest precedence. It sets up a basic `ArgumentParser`, defines a config file and an environment variable, then parses the arguments to show the effective values based on precedence. It also shows how to add an argument to specify an alternative config file."},"warnings":[{"fix":"Upgrade to v1.7.4 or later. For older versions, explicitly pass environment variable values as command-line arguments to the subparser, or ensure critical arguments are defined directly on subparsers with `env_var` if not relying on `auto_env_var_prefix`.","message":"Prior to v1.7.4, environment variables were ignored when used in conjunction with subparsers. This could lead to unexpected behavior where subcommands would not receive their intended environment-sourced configuration.","severity":"breaking","affected_versions":"<1.7.4"},{"fix":"Upgrade to v1.7.3 or later. These versions contain fixes for proper handling of `nargs=REMAINDER` and the `--` separator, ensuring config file arguments are inserted correctly into the argument list.","message":"In versions prior to v1.7.3/v1.7.4, using `nargs=argparse.REMAINDER` or the `--` separator could lead to config file options being 'swallowed' or incorrectly parsed. This resulted in config file settings not being applied or arguments being misinterpreted as positional arguments.","severity":"breaking","affected_versions":"<1.7.3"},{"fix":"Ensure that arguments passed to the `ArgumentParser` constructor adhere to the expected types (e.g., `config_file_parser_class` must be a subclass of `ConfigFileParser`, lists/tuples for file path arguments). Refer to the documentation for correct parameter types.","message":"ConfigArgParse introduced stricter input validation for `ArgumentParser.__init__()` in v1.7.4. Passing incorrect types for parameters like `config_file_parser_class`, `formatter_class`, `default_config_files`, `args_for_setting_config_path`, or `args_for_writing_out_config_file` will now raise a `TypeError` with a clear message.","severity":"gotcha","affected_versions":">=1.7.4"},{"fix":"Understand the 'Special Values' handling. For boolean flags (`action='store_true'`), `key=true` is interpreted as `\"--key\"` (setting it to True). `key=false` or omitting the key will result in `False`. For lists, `key = [item1, item2]` is generally supported by modern parsers (e.g., `TomlConfigParser`), or ensure your parser handles multiple lines if you intend to append.","message":"When defining boolean flags with `action='store_true'` or `action='store_false'`, set them as `key = true` or `key = false` in config files or environment variables. For arguments with `action='append'` (lists), use `key = [value1, value2]` or multiple `key = value` lines (depending on parser). A simple `key = value` will be treated as `--key value`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always define a long argument (`--my-option`) if you intend for an option to be configurable via a config file. The corresponding config file key can then be `my-option` or `--my-option`.","message":"Only command-line arguments that have a long version (i.e., start with `--`, e.g., `--my-option`) can be set via config files. Short arguments (e.g., `-m`) cannot directly be specified in config files.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade to v1.7.3 or later to benefit from fixes addressing these parsing inconsistencies and `SyntaxError` issues for TOML and INI formats.","message":"Prior to v1.7.3, the TOML parser might only read the first matching section, or INI-style config parsers could encounter `SyntaxError`s due to `ast.literal_eval` leaks.","severity":"gotcha","affected_versions":"<1.7.3"}],"env_vars":null,"last_verified":"2026-04-05T00:00:00.000Z","next_check":"2026-07-04T00:00:00.000Z"}