Install & Compatibility
Where this runs
tested against v0.1.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.95 runs
installs and imports cleanly · install 0.0s · import 0.170s · 19.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.7s · import 0.146s · 20MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ArgumentParser
✓ from simple_parsing import ArgumentParser
✗ from argparse import ArgumentParser
simple-parsing's ArgumentParser is a subclass of argparse.ArgumentParser, providing additional functionality like `add_arguments` for dataclasses.
parse
✓ from simple_parsing import parse
This provides a simplified API for directly parsing a single dataclass without explicit ArgumentParser instantiation.
This quickstart demonstrates two common ways to use `simple-parsing`: using the `ArgumentParser` for more complex scenarios involving multiple argument groups or standalone arguments, and using the simplified `parse` function for directly obtaining an instance of a single dataclass from command-line arguments. It showcases how dataclasses define arguments and how they are populated.
from dataclasses import dataclass
from simple_parsing import ArgumentParser, parse
import os
@dataclass
class CommonOptions:
"""Common options for a script."""
seed: int = 42
log_level: str = "INFO"
@dataclass
class TrainingOptions:
"""Options specific to training."""
learning_rate: float = 1e-4
epochs: int = 10
output_dir: str = os.environ.get('OUTPUT_PATH', './outputs')
# Method 1: Using ArgumentParser (for multiple dataclasses or custom args)
parser = ArgumentParser()
parser.add_arguments(CommonOptions, dest="common")
parser.add_arguments(TrainingOptions, dest="train")
args_parser = parser.parse_args(['--seed', '100', '--learning_rate', '0.01'])
print(f"Parsed with ArgumentParser: Common: {args_parser.common}, Train: {args_parser.train}")
# Method 2: Simplified API (for single dataclass parsing)
args_simplified = parse(TrainingOptions, args=['--epochs', '20'])
print(f"Parsed with simplified API: {args_simplified}")
Debug
Known issues
breakingVersion 0.1.8 drops support for Python 3.8. Users on Python 3.8 or older must upgrade their Python environment to 3.9+ or use an older version of `simple-parsing`.fixUpgrade Python to 3.9 or newer, or pin `simple-parsing<0.1.8`.
affects: >=0.1.8
gotchaWhen using `ArgumentParser`, ensure you import `simple_parsing.ArgumentParser` and not `argparse.ArgumentParser`. Only the `simple_parsing` version provides methods like `add_arguments` for dataclass integration.fixChange `from argparse import ArgumentParser` to `from simple_parsing import ArgumentParser`.
affects: All
deprecatedOlder versions of simple-parsing (e.g., <0.0.3) used `ParseableFromCommandLine` as a base class for dataclasses. While it might still function, the recommended API for grouping arguments with dataclasses is `parser.add_arguments(YourDataclass, dest="your_dest")` or using the `simple_parsing.parse` function for single dataclass parsing.fixRefactor dataclasses to not inherit from `ParseableFromCommandLine` and use `parser.add_arguments()` or `simple_parsing.parse()` instead.
affects: <0.0.3 (older API style)
gotchaWhen using `parser.add_arguments(Dataclass, dest="attribute_name")`, the `dest` argument is crucial. It specifies the attribute name on the parsed arguments object where the dataclass instance will be stored. Omitting it or using a conflicting `dest` can lead to unexpected argument flattening or overwrites.fixAlways explicitly define a unique `dest` for each dataclass added via `add_arguments` to ensure proper grouping and access to the parsed dataclass instance (e.g., `args.attribute_name`).
affects: All
Errors
Common errors & fixes
TypeError: mutable default <class 'list'> for field <field_name> is not allowed: use default_factory
Dataclasses (which simple-parsing leverages) disallow mutable default arguments directly in field definitions to prevent unexpected shared state across instances.
fixUse `dataclasses.field(default_factory=list)` (or other mutable type) instead of directly assigning `list=[]` or `dict={}` in your dataclass field definition. error: unrecognized arguments: --some-argument
The command-line argument provided was not defined in any of the dataclasses registered with `simple_parsing.ArgumentParser` or its sub-parsers.
fixCheck for typos in the argument name, ensure the argument is correctly defined in the relevant dataclass, or verify that the correct sub-parser is active if using subcommands.
error: argument --<field_name>: conflicting option string(s): --<field_name>
An argument with the same name (or short/long flag) has been defined multiple times within the same argument parser context, often due to overlapping field names in nested or inherited dataclasses.
fixEnsure that argument names are unique across all dataclass fields registered with the parser, especially when dealing with nested structures or sub-parsers.
ModuleNotFoundError: No module named 'simple_parsing'
The `simple-parsing` library is not installed in the current Python environment, or there is a typo in the import statement.
fixInstall the library using `pip install simple-parsing` and ensure the import statement is `from simple_parsing import ArgumentParser` (or similar).
ValueError: invalid literal for int() with base 10: 'not_an_int'
The value provided for a command-line argument could not be successfully converted to the expected type hint (e.g., `int`, `float`) defined in the dataclass field.
fixProvide a command-line value that matches the expected type, for example, an integer for an `int` field, or a floating-point number for a `float` field.
Upgrade
Version history
0.1.9latest on PyPI · released Jul 27, 2026
Audit
Dependencies
No dependency data recorded yet.