Skip to content

Env

invoke_tasklib.env

Environment and dependency management tasks (env.*).

The tasks create and update the virtual environment with uv (create-venv, install, update), show it (show-installed- packages, show-python-config) and check the tools that the other tasks run (check-tools). The dependency groups come from tasklib.groups and the Python version from tasklib.package.python_version.

invoke_tasklib.env.NAMESPACE module-attribute

NAMESPACE = 'env'

The name of the namespace of the tasks of this module.

invoke_tasklib.env.check_tools

check_tools(c: Context) -> None

Check which tools of the tasks are available.

Every program (ruff, ty, pyright, uv, ...) and every Python module (pytest, coverage and the pytest plugins) that the tasks run is looked up, and one line per tool says where it was found, or how to install it. The tools are sorted by name. All the tools are listed, so one run shows everything that is missing. The config of the project is not needed, so the task can be run before anything is set up.

Parameters:

Name Type Description Default
c Context

The invoke context.

required

Raises:

Type Description
Exit

With the code 127 if a tool is missing.

invoke_tasklib.env.create_venv

create_venv(
    c: Context, *, yes: bool = False, dry_run: bool = False
) -> None

Create a virtual environment and install the project in it.

The project is installed with env.install (uv sync), so the environment gets invoke within the bounds of the project, and the packages that tasks.py imports, such as invoke-tasklib.

Note

The virtual environment will be created in the .venv directory and any existing environment will be cleared, after a confirmation (--yes turns it off). The task itself runs with invoke, which is often installed in that very environment, so invoke must be available from somewhere else to run it.

Parameters:

Name Type Description Default
c Context

The invoke context.

required
yes bool

If True, do not ask for a confirmation before clearing an existing .venv.

False
dry_run bool

If True, print what would be done and do nothing.

False

Raises:

Type Description
Exit

If the confirmation is refused or cannot be asked.

invoke_tasklib.env.install

install(
    c: Context,
    *,
    optional_deps: bool = True,
    groups: str | None = None,
) -> None

Install the dependencies and the package (editable).

uv sync installs the project itself in editable mode, so no other command is needed.

Parameters:

Name Type Description Default
c Context

The invoke context.

required
optional_deps bool

If True, install all optional dependencies defined in the project extras. Default is True.

True
groups str | None

Comma-separated list of dependency groups to install, e.g. "dev,docs". Use an empty string to install no group. A group listed twice is installed once. Defaults to the tasklib.groups.install config value ("dev" unless overridden in invoke.yaml).

None

invoke_tasklib.env.show_installed_packages

show_installed_packages(c: Context) -> None

Show the installed packages.

It runs uv pip list.

Parameters:

Name Type Description Default
c Context

The invoke context.

required

invoke_tasklib.env.show_python_config

show_python_config(c: Context) -> None

Show the python configuration.

It lists the Python versions that uv knows, the one it would use, and the python of the PATH. Having no python on the PATH is not an error of the task, and neither is a Python version that uv would use but that is not installed (for example a pinned .python-version).

Parameters:

Name Type Description Default
c Context

The invoke context.

required

invoke_tasklib.env.update

update(c: Context, *, groups: str | None = None) -> None

Update dependencies and pre-commit hooks.

The dependencies and the hooks are updated to their latest versions. The hooks are only updated if the project has a .pre-commit-config.yaml file. The uv tools installed on the machine are not touched: they are not part of the project.

Parameters:

Name Type Description Default
c Context

The invoke context.

required
groups str | None

Comma-separated list of dependency groups to reinstall after updating, e.g. "dev,docs". Defaults to the tasklib.groups.update config value ("dev,docs" unless overridden in invoke.yaml).

None
Note

The lock file is upgraded first, then the environment is synced once with the dependency groups.

Warning

This may introduce breaking changes. Review the changes and run tests after updating.