poetry-run

Run a command inside the virtual environment

$ poetry run [command]

$ poetry run [command] [argument1 argument2 ...]

$ poetry run [script_name]

$ poetry run python [path/to/script.py]

poetry run [] [...]

--help
    Display help for the run command.

-q, --quiet
    Do not output any message.

-v, --verbose (-vvv)
    Increase the verbosity of messages.

-V, --version
    Display this application version.

--ansi
    Force ANSI output.

--no-ansi
    Disable ANSI output.

-n, --no-interaction
    Do not ask any interactive question.

--profile
    Display timing and memory usage profile.

--no-plugins
    Disables all plugins.

--
    Separates Poetry options from the command and its arguments. Arguments after this are passed directly to the executed command.


    The name of the executable or script to run. This command must be available within the project's virtual environment.

[...]
    Optional arguments to be passed directly to the <command>.

The poetry run command allows you to execute any arbitrary command within the context of your Poetry-managed project's virtual environment. This is crucial for ensuring that scripts, tests, or other applications use the exact dependencies specified in your pyproject.toml file, preventing conflicts with global Python installations or other projects.

When you use poetry run, Poetry first activates the project's virtual environment (creating it if it doesn't exist), making all installed project dependencies and their executables available in the PATH. It then proceeds to execute the specified command with any provided arguments. This isolation is a cornerstone of reproducible development environments, guaranteeing that your development, testing, and production environments behave consistently.

poetry run relies on the project having a virtual environment set up and activated by Poetry. If the project isn't properly initialized with Poetry or the virtual environment is broken, the command may fail.

Shell built-ins (like cd, export) cannot be executed directly via poetry run as it executes a new process. For such cases, you might need to wrap them in a shell script or use a different approach.

poetry run provides a convenient and reliable way to interact with executables and scripts that are part of your project's dependencies or are themselves part of the project. It ensures that the correct version of Python and all required packages are in the PATH for the execution, preventing "it works on my machine" issues related to environment discrepancies.

poetry run pytest
Executes the pytest test runner installed as a development dependency.

poetry run python my_script.py arg1 arg2
Runs a Python script within the project's environment, passing arguments.

poetry run -- python -m http.server 8000
Starts a simple HTTP server, demonstrating the use of -- to separate Poetry options from Python's options.

Poetry, a modern Python dependency manager and packager, was first released in 2018. The poetry run command has been a fundamental part of its design since early versions, providing a robust and integrated way to interact with project executables within their isolated virtual environments. It addresses a common pain point in Python development by automating the activation of virtual environments, simplifying workflows compared to manually activating environments (e.g., source .venv/bin/activate) before executing commands.

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