Install & Compatibility
Where this runs
tested against v1.4.6 · 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.192s · 17.9MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.6s · import 0.160s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
plac
✓ import plac
The primary way to import the library.
call
✓ plac.call(main_function)
✗ plac.main(main_function)
The entry point for plac to parse arguments and execute your main function is `plac.call()`.
This quickstart demonstrates how Plac automatically generates command-line arguments from a function's signature and annotations. Run this script and try `python your_script.py my_model -i 200 -d` or `python your_script.py -h` to see the generated help message.
import plac
def main(model, iter: ('iterations for training', 'option', 'i', int)=100, debug: ('enable debug mode', 'flag', 'd')=False):
""" A script for machine learning """
print(f"Model: {model}, Iterations: {iter}, Debug: {debug}")
if __name__ == '__main__':
plac.call(main)
plac --version
Debug
Known issues
breakingThe `plac` server functionality, which relied on Python's `asyncore` and `asynchat` modules, was removed in `plac` v1.4.0 due to their deprecation and subsequent removal in Python 3.12+. This affects users of `plac`'s experimental server, which is no longer directly supported by `plac` itself.fixMigrate any `plac` server implementations to use `asyncio` or another modern asynchronous framework. The `plac` core CLI parsing remains unaffected.
affects: 1.4.0+
gotchaPlac does not support the `destination` concept found in `argparse`. If an argument name in your function signature clashes with a Python keyword (e.g., trying to define `--yield`), it's impossible to implement directly. You must change the argument name or use `argparse` if such a name is critical.fixRename function arguments to avoid Python keywords if they are intended to be exposed as command-line options/flags.
affects: All versions
gotchaPlac does not directly support 'required options'. Its design philosophy aligns with `argparse`'s guideline that options should generally be optional. If a parameter is truly required, it should typically be defined as a positional argument in your function signature.fixUse positional arguments for truly required inputs. If an option-like syntax is desired for a required value, consider custom validation or switch to `argparse` directly for more fine-grained control over 'required' options.
affects: All versions
gotcha`plac.call()` handles invalid command-line input by printing an error message to `stderr` and then raising a `SystemExit`. This behavior, while standard for CLI applications, can disrupt automated tests by abruptly exiting the Python interpreter.fixFor testing `plac` applications, it's recommended to wrap `plac.call()` in a `try...except SystemExit` block to catch the exit gracefully and inspect `sys.stderr` for error messages without terminating the test runner.
affects: All versions
breakingPython 3.13.0a4 and newer versions have introduced changes in the help text output format. This can cause existing `plac` application tests to fail if they rely on exact string comparisons of the generated `help` output.fixAdjust tests to be less brittle regarding whitespace and formatting in help messages, or conditionally update expected help strings based on the Python version being used. Focus on verifying key components of the help message rather than exact character-for-character matches.
affects: 1.4.3+ on Python 3.13+
Errors
Common errors & fixes
error: the following arguments are required: <argument_name>
The user failed to provide a value for a command-line argument that `plac`'s automatically generated parser marked as required based on the function's signature (e.g., a parameter without a default value).
fixProvide the necessary argument on the command line when running the script (e.g., `python your_script.py required_value`).
error: argument <argument_name>: invalid choice: '<value>' (choose from '<choice1>', '<choice2>', ...)
The user provided a value for an argument that is not among the allowed `choices` explicitly specified using a `plac.pos` or `plac.opt` decorator.
fixConsult the script's help message (`python your_script.py -h`) and provide one of the valid choices for the argument.
error: unrecognized arguments: <argument_name>
The user passed an argument to the script that was not defined in the function signature `plac` is parsing, or it was passed in an incorrect format (e.g., as a positional argument when it should have been an option).
fixReview the function signature that `plac` is parsing and ensure all command-line arguments correspond to defined parameters and are used in the correct format (positional, option, or flag). Check for typos or extraneous arguments.
ModuleNotFoundError: No module named 'plac'
The `plac` library is not installed in the Python environment where the script is being executed.
fixInstall the `plac` library using pip: `pip install plac`
Upgrade
Version history
1.4.6latest on PyPI · released Aug 17, 2026
Audit
Dependencies
No dependency data recorded yet.