User Guide

invoke-tasklib groups its tasks into namespaces, one per module. Each namespace maps to one page in this guide.

All Tasks at a Glance

Each task either checks/reports (read-only, exits non-zero on violations) or mutates (formats, builds, publishes) — the Mutates? column below flags which.

Namespace	Task	Behavior	Mutates?
Format	format.check-python	Check Python formatting with ruff	❌
Format	format.fix-python	Format Python code with ruff	✅
Format	format.check-docstrings	Check docstring formatting with docformatter	❌
Format	format.fix-docstrings	Format docstrings with docformatter	✅
Format	format.check-shell	Check shell scripts with shellcheck	❌
Format	format.fix-shell	Format shell scripts with shfmt	✅
Lint	lint.check-lint	Check code linting with ruff	❌
Lint	lint.fix	Fix auto-fixable linting issues with ruff	✅
Imports	imports.check-cycles	Check for cyclic import dependencies	❌
Types	types.check	Check type hints with pyright	❌
Test	test.doctest	Run doctests on source code and markdown files	❌
Test	test.doctest-src	Run doctests on source code	❌
Test	test.doctest-markdown	Run doctests on Python examples in markdown	❌
Test	test.unit	Run unit tests	❌
Test	test.integration	Run integration tests	❌
Test	test.functional	Run functional tests	❌
Test	test.all	Run unit, integration, and functional tests	❌
Test	test.coverage-report	Generate an HTML/terminal report from coverage data	❌
Test	test.benchmark	Run performance benchmarks	❌
Env	env.create-venv	Create a virtual environment and install invoke	✅
Env	env.install	Install project dependencies and the package	✅
Env	env.update	Update dependencies and pre-commit hooks	✅
Env	env.show-installed-packages	Show installed packages	❌
Env	env.show-python-config	Show the Python configuration	❌
Release	release.build	Build the package and verify installation	✅
Release	release.pypi	Build and publish the package to PyPI	✅
Doc	doc.publish-dev	Publish development (unstable) docs	✅
Doc	doc.publish-latest	Publish latest (stable) docs	✅
Security	security.audit	Audit dependencies for known vulnerabilities	❌
Clean	clean	Remove build artifacts and caches	✅
Config	(none — shared config)	Config resolution used by all tasks above	—

Everyday Workflow

A typical local development loop looks like this:

invoke format.fix-python format.fix-docstrings   # auto-fix formatting
invoke lint.check-lint imports.check-cycles types.check  # check quality
invoke test.unit --cov                            # run tests with coverage

And what CI typically runs (nothing should modify the working tree):

invoke format.check-python format.check-docstrings lint.check-lint imports.check-cycles types.check
invoke test.all --cov

Since Invoke lets you chain multiple task names in one command, all of the above run as a single invoke call each.

External Tools

Tasks are thin wrappers around external command-line tools. Each is expected to be available on PATH (or installed via env.install/env.create-venv):

Tool	Used by
ruff	format.check-python, format.fix-python, lint.check-lint
docformatter	format.check-docstrings, format.fix-docstrings
shellcheck	format.check-shell
shfmt	format.fix-shell
pyright	types.check
pytest	test.* except test.doctest and test.doctest-markdown
pytest-benchmark	test.benchmark
uv	env.*, release.*
twine (via uvx)	release.build --check
mike	doc.*
feu + packaging	doc.publish-latest
pip-audit (via uv run)	security.audit

Most of these come from your project's own dev/docs dependency groups; see Env for how env.install wires them up, and the Troubleshooting guide if a task fails with a "command not found" error.

See Also

• Get Started: installing invoke-tasklib and wiring up a new project.
• Config: the shared configuration all tasks read from.
• Troubleshooting: common errors and how to fix them.