Install & Compatibility
Where this runs
tested against v0.3.9 · 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.920 runs
installs and imports cleanly · install 0.0s · import 0.203s · 21.6MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 2.6s · import 0.197s · 23MB
20MB installed
● package 20MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
bind
✓ from argbind import bind
# or use as decorator: @argbind.bind()
parse_args
✓ from argbind import parse_args
# or: args = argbind.parse_args()
scope
✓ from argbind import scope
# or: with argbind.scope(args):
load_args
✓ from argbind import load_args
# or: args = argbind.load_args('config.yaml')
This quickstart demonstrates how to define a function with `argbind.bind()`, parse arguments (either defaults, command-line, or from a YAML file), and execute the bound function within an `argbind.scope` context. Arguments are prefixed with the function name (e.g., `--greet.name`).
import argbind
@argbind.bind()
def greet(name: str = 'World', excited: bool = False):
"""Greets the given name, optionally with excitement."""
message = f"Hello, {name}"
if excited:
message += "!"
print(message)
if __name__ == '__main__':
# In a real CLI, this would parse sys.argv
# For quickstart, simulate args or load from file
# Example 1: Default execution
print('--- Running with defaults ---')
args_default = argbind.parse_args([]) # No CLI args provided
with argbind.scope(args_default):
greet()
# Example 2: Override from simulated CLI args
print('\n--- Running with CLI override ---')
# Simulate `python your_script.py --greet.name Alice --greet.excited True`
args_cli = argbind.parse_args(['--greet.name', 'Alice', '--greet.excited', 'True'])
with argbind.scope(args_cli):
greet()
# Example 3: Load from a YAML file
print('\n--- Running from YAML file ---')
config_content = """
greet.name: Bob
greet.excited: False
"""
with open('config.yaml', 'w') as f:
f.write(config_content)
args_yaml = argbind.load_args('config.yaml')
with argbind.scope(args_yaml):
greet()
# Clean up (optional for quickstart, but good practice)
import os
os.remove('config.yaml')
argbind --version
Debug
Known issues
gotchaBoolean arguments overridden from a YAML file cannot be easily unset (flipped to `False`) from the command line. If a boolean is `True` in YAML, passing `--func.arg False` may not work as expected.fixFor arguments that need to be dynamically flippable between `True` and `False` from both YAML and CLI, define them as `int` (0 or 1) instead of `bool`. For example, use `--func.arg 0` or `--func.arg 1` on the command line.
affects: All versions up to 0.3.9
gotchaPositional arguments specified in a `.yml` configuration file will override any positional arguments provided directly on the command line. This can lead to unexpected behavior if a user expects CLI arguments to always take precedence for positional parameters.fixAvoid saving positional arguments within `.yml` files. Instead, use `.yml` files exclusively for keyword arguments, and pass positional arguments directly via the command line when running the script.
affects: All versions up to 0.3.9
gotchaBound function names must be unique across your entire application. ArgBind resolves function arguments by their immediate function name, not their fully qualified path or module.fixEnsure that any function decorated with `@argbind.bind()` has a unique name. If you have similarly named functions in different modules, consider refactoring or using distinct aliases if ArgBind supported them (which it does not explicitly mention).
affects: All versions up to 0.3.9
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'argbind'
The 'argbind' library has not been installed in your Python environment.
fixRun `pip install argbind` in your terminal to install the library.
TypeError: func() got multiple values for keyword argument 'arg'
This typically occurs when an argument is provided through multiple mechanisms (e.g., command line, YAML file, and direct function call) and their priority is not correctly understood, or a default value is conflicting.
fixUnderstand ArgBind's argument priority: explicit Python code arguments > command-line arguments > YAML file arguments > default keyword arguments. Check your calls and configurations for conflicts and remove redundant argument specifications.
The boolean flag I'm passing on the command line isn't changing the value set in my YAML config.
ArgBind has a known behavior where a boolean argument set to `True` in a YAML file cannot be overridden back to `False` using command-line arguments in certain scenarios.
fixRedefine the problematic boolean argument as an integer (`int`) in your function signature, using `0` for `False` and `1` for `True`. Then, specify the value on the command line as `--func.arg 0` or `--func.arg 1`.
Upgrade
Version history
0.3.9latest on PyPI · released May 24, 2024
Audit
Dependencies
pyyamlrequiredRequired for YAML configuration file parsing.
docstring-parserrequiredUsed for parsing function docstrings to generate argument help messages.