Skip to content

Env

📖 This page describes the invoke_tasklib.env module, which provides tasks to set up and inspect a project's Python environment using uv.

Overview

Task Behavior
env.create-venv Creates a virtual environment and installs the project
env.install Installs project dependencies and the package (editable)
env.update Updates dependencies and pre-commit hooks
env.check-tools Checks which tools of the tasks are available
env.show-installed-packages Shows the installed packages
env.show-python-config Shows the Python configuration

Creating a Virtual Environment

invoke env.create-venv

Creates (or recreates) a .venv with uv venv, using the package.python_version from the resolved config if it is set (--python), and the version that uv chooses otherwise (the .python-version file, then requires-python), and then runs env.install (uv sync), so the environment has invoke within the bounds of the project and the packages that tasks.py imports, such as invoke-tasklib. The task is run with invoke, so invoke must already be available (for example through uv tool install invoke) to run it. Use env.install to choose the dependency groups.

Warning

This clears any existing .venv, so the task asks for a confirmation when the directory exists (--yes turns it off, and is needed without a terminal). --dry-run prints what would be done and does nothing. The invoke that runs the task often lives in that .venv: run it from another environment.

Installing Dependencies

invoke env.install

Runs uv sync, which also installs the package itself in editable mode. If the project has a uv.lock, the task passes --locked, which fails if the lock file is out of date with pyproject.toml instead of silently using it (run uv lock to refresh it). Without a uv.lock (common for libraries), the task says so, and uv sync resolves the dependencies and creates the file.

Flag Default Adds to uv sync
--optional-deps on --all-extras
--groups groups.install (default dev) --group <name> for each comma-separated group

--groups takes a comma-separated list of dependency groups to install, e.g. dev,docs. A group listed twice is installed once. Pass an empty string to skip installing any group.

Disable the on-by-default optional deps, or override the groups, with:

invoke env.install --no-optional-deps --groups ""
invoke env.install --groups dev,docs

The default value of --groups comes from the resolved config's groups.install ("dev" unless overridden in invoke.yaml), so a project with more groups than dev/docs can change the default once instead of passing --groups on every call.

Updating Dependencies

invoke env.update

Runs uv lock --upgrade, updates the pre-commit hooks (pre-commit autoupdate, only if the project has a .pre-commit-config.yaml file; otherwise a ⏭️ line says so), and reinstalls the project with the groups from --groups (default: the resolved config's groups.update, "dev,docs" unless overridden).

invoke env.update --groups dev,docs,test

Warning

Updating dependencies may introduce breaking changes. Review the changes and run the test suite afterward.

Inspecting the Environment

invoke env.show-installed-packages
invoke env.show-python-config

env.show-python-config prints the installed Python versions known to uv, the interpreter uv would select, and the interpreter currently on PATH (python: not found when there is none, which is not an error). A Python version that uv would select but that is not installed (for example a pinned .python-version) is not an error either.

Checking the Tools

invoke env.check-tools

env.check-tools gives a single view of the tools that the tasks run: the programs (uv, uvx, git, ruff, ty, pyright, mypy, docformatter, codespell, pre-commit, shellcheck, shfmt, mkdocs, mike) and the Python modules of the interpreter (pytest, coverage, xdoctest, pytest_timeout, pytest_cov, pytest_benchmark). Each tool has one line, with its path when it is available:

✅ ruff: /project/.venv/bin/ruff
❌ 'shfmt' was not found on the PATH or next to the Python interpreter. Install shfmt with your system package manager, ...

The tools are sorted by name. All the tools are listed, so one run shows everything that is missing. The task does not read the config, so it can be run before invoke.yaml is set up. It exits with the code 127 if a tool is missing, so it can also gate a CI job. It does not install anything: see env.install.

See Also