poetry run: Run in the Project Env Command Reference

Run tools inside the project venv without activating a shell.

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

Common flags / usage

poetry run pytest -- run tests in the project env
poetry run python -m mypackage -- run a module
poetry run ruff check . -- run a linter installed in the env
poetry run python -c "..." -- run an inline snippet

Example

shell

- run: poetry install --no-interaction
- run: poetry run pytest -q
- run: poetry run ruff check .

In CI

poetry run needs an environment, so poetry install must run first or the command fails. Using poetry run avoids the cross-step activation problem -- each invocation gets the right interpreter and packages on PATH.

Key takeaways

poetry run executes a command inside the project env for one invocation.
Run poetry install before poetry run, or the env will not exist.
It sidesteps the cross-step venv activation problem in CI.

Related guides

poetry install: Install from Lock Command ReferenceReference for poetry install in CI: installing from poetry.lock, the --no-root, --only, and --no-interaction… pytest: Run Tests Command Reference for CIReference for pytest in CI: running the suite, useful flags, why python -m pytest fixes import errors, and a… poetry lock: Resolve the Lockfile Command ReferenceReference for poetry lock in CI: resolving dependencies into poetry.lock without installing, the consistency…