poetry-python

Install the specified Python version

$ poetry python install [3.13.1]

$ poetry python list

$ poetry python list --managed

$ poetry python remove [3.13.1]

poetry-python [-h] [-v] [-B] [-c command | -m module | script-file] [arguments...]

-h, --help
    Display help message and exit for the underlying Python interpreter.

-V, --version
    Display the Python version number of the virtual environment's interpreter and exit.

-c <command>
    Execute the specified Python command string using the project's Python.

-m <module>
    Run the specified Python library module as a script within the project's environment.

-B
    Do not write .pyc files on import (byte-code cache).

-E
    Ignore all PYTHON* environment variables (such as PYTHONPATH, PYTHONHOME) when starting the interpreter.

<script-file>
    The path to a Python script file to execute using the virtual environment's interpreter.

<arguments...>
    Arguments passed to the Python script or module being executed.

The poetry-python command, while not typically invoked directly by users, serves as an internal shim or wrapper for the Python interpreter managed by the Poetry dependency management tool. Its primary function is to ensure that when a Python command is executed within a Poetry project's context (e.g., via poetry run or within a poetry shell), the correct Python executable from the project's virtual environment is utilized.

Instead of directly calling the system's default Python, poetry-python guarantees that the interpreter associated with the project's specific dependencies is invoked. This is crucial for maintaining isolated and reproducible development environments. Any arguments or options passed to poetry-python are generally forwarded directly to the underlying virtual environment's python interpreter, making it behave like the standard python command but with the correct environment context. It abstracts away the complexity of managing virtual environment activation for Python script execution.

poetry-python is primarily an internal mechanism of the Poetry dependency manager and is generally not intended for direct user invocation. Users should typically interact with their project's Python interpreter through poetry run python or by activating the shell with poetry shell.

The exact behavior and even the presence of a directly executable poetry-python shim might vary slightly depending on the Poetry version and how it was installed. Relying on its direct execution could lead to unexpected behavior or compatibility issues in future Poetry updates.

While not typically run directly, poetry-python (or similar internal logic) is implicitly invoked by Poetry when you use commands like poetry run python or poetry run <script>. Poetry handles the necessary environment setup, including setting the correct PATH and other environment variables, before executing the command. This ensures that the Python interpreter and its associated packages from the project's virtual environment are correctly utilized.

The concept of a wrapper like poetry-python evolved as a fundamental component of Poetry's design philosophy, which emphasizes strong project isolation and reliable dependency management. From its early development, Poetry aimed to abstract away the complexities of virtual environments, making it seamless for developers to execute scripts and commands using the correct project-specific Python interpreter. This wrapper ensures that the python command, when invoked within a Poetry context, always points to the virtual environment's interpreter, solidifying Poetry's promise of reproducible builds and consistent development environments.

poetry(1), python(1), venv(1)