poetry run: Run a Command in the Project Env

Run tools inside the project venv without activating a shell.

poetry run executes a command with the project’s virtual environment active for that one invocation. CI uses it to run pytest, linters, and scripts without an activation step.

What it does

Runs the given command using the project’s managed environment, so the right interpreter and installed packages are on PATH for that command only.

Common usage

Terminal

poetry run pytest
poetry run python -m mypackage
poetry run ruff check .

Common CI error: environment not created

If poetry install has not run on the runner, there is no environment for poetry run to use and the command fails. Install first, then run.

Terminal

# Order matters in CI:
poetry install --no-interaction
poetry run pytest

Related guides

poetry install: Install from the LockfileHow poetry install resolves and installs dependencies from poetry.lock, the --no-root and --only flags useful… poetry env use: Select the Python InterpreterHow poetry env use binds the project to a specific Python interpreter, why CI matrices need it, and the inter… python -m pytest: Run Tests with the Project on sys.pathWhy python -m pytest beats a bare pytest in CI, how it adds the current directory to sys.path, and the import…