Troubleshooting & FAQ¶
'tasklib.package.name' must be set in invoke.yaml¶
Almost every task reads the config, which requires
tasklib.package.name. An invalid config is reported with this one-line message and the exit
code 2. Add an invoke.yaml at your project root (next to tasks.py) with at
least:
tasklib:
package:
name: my_package
See Get Started and Config for the full schema.
inv must run from the project root, where tasks.py is: ...¶
Invoke looks for tasks.py in the parents of the current directory and loads the invoke.yaml
next to it, but it does not change directory. The tasks use paths relative to the current directory
(tests/unit, pyproject.toml, dist, ...), so from a subdirectory they would look in the wrong
place, and a task like test.unit would skip the missing tests/unit directory and pass. A task
that reads the config now exits with code 2 and this message instead. Run inv from the directory
of tasks.py, as in cd <project root> && inv check.all, or use the make targets.
'ruff' was not found on the PATH or next to the Python interpreter¶
Before running a command, the tasks check that its program (ruff, ty, uv, mike, ...) is on
the PATH or in the directory of the Python interpreter that runs invoke (so .venv/bin/inv finds
the programs of .venv/bin without an activation), and exit with code 127 if it is not. The commands
run with that directory first on their PATH. Install the project tools with invoke env.install
(the dev group has the linters and test tools, the docs group has mike). Run
invoke env.check-tools to list every missing tool at once; invoke check does the same for the
steps it is going to run.
The hint depends on the program: uv and uvx point to the installation page of uv
(env.install itself needs it), git, shellcheck and shfmt to the system package manager, and
codespell to the project dependencies. The tools of the dev group (ruff, ty, pyright,
docformatter, pre-commit, pytest and its plugins) and of the docs group (mkdocs, mike)
name their group, for example uv sync --group docs.
Only the first word of a command is checked. A program given by a path (./run.sh,
/usr/bin/tool, the running interpreter) is not looked up. A command is a list of words, which
run quotes: it is never parsed as a shell line, so a shell builtin, function or alias is not
found, and a pipeline (a | b) or a list (a && b) cannot be written. Pass check=False to run
to run a program that is not on the PATH without the check, see
Writing a Custom Task.
The module of python -m <module> is checked too (for example pytest), and is reported as
The Python module 'pytest' is not installed for ... instead of Python's own No module named.
The pytest plugins of the options are checked as well: --xdoctest needs xdoctest, --timeout
needs pytest-timeout, --cov* (also --no-cov) needs pytest-cov and --benchmark-* needs
pytest-benchmark. A missing plugin is reported as The option --xdoctest needs the pytest plugin 'xdoctest' with the
command that adds it, instead of pytest's unrecognized arguments.
invoke: command not found after installing¶
invoke-tasklib depends on invoke, but installing a library into a virtual environment does not
always put its console scripts on PATH the way you expect. Make sure:
- Your virtual environment is activated (
source .venv/bin/activate), or - You run it via
uv run invoke ..., or invokeitself is installed as a tool (uv tool install invoke). Note thatenv.create-venvinstalls the project, withinvoke, into the new.venv, not as a tool.
invoke --list shows no tasks / ns is empty¶
Check that tasks.py actually builds and exposes ns:
# tasks.py
from invoke_tasklib import make_ns
ns = make_ns()
Invoke discovers tasks from a module-level ns (or namespace) variable in tasks.py; if you
renamed the variable or wrapped it, Invoke won't find it. (The pre-built invoke_tasklib.ns was
removed: from invoke_tasklib import ns raises an ImportError, use make_ns().)
A task fails with "command not found" (ruff, ty, shellcheck, ...)¶
invoke-tasklib tasks are wrappers around external CLI tools — it does not vendor them. Run
invoke env.check-tools to see, in one list, which tools are available and which are missing.
Install the missing tool, either directly or via your project's dependency groups:
invoke env.install # installs dev deps: ruff, ty, pytest, ...
invoke env.install --groups dev,docs # additionally installs mike
shellcheck and shfmt are not Python packages; install them with your system package manager
(e.g. brew install shellcheck shfmt on macOS) — see the
Format page. The full external-tool matrix is in the
User Guide overview.
doc.publish-latest fails with No version tag found¶
doc.publish-latest reads the last git tag that looks like v1.2.3. Create a release tag (and
fetch the tags in CI: git fetch --tags), or skip the tag lookup by passing the version:
invoke doc.publish-latest --version 1.2
doc.publish-latest fails with Refusing to publish ... as latest¶
A newer version of the docs is already published, so publishing this one would move latest
backwards. Pass --force if that is what you want.
See Doc.
The output has [ok] and [fail] instead of emojis¶
On a terminal that cannot encode them (an ASCII locale, PYTHONIOENCODING=ascii), the progress
messages use the tags [ok], [fail] and [skip] and leave the other emojis out. Use a UTF-8
locale (for example LANG=C.UTF-8) to get the emojis. Set INVOKE_TASKLIB_ASCII=1 to get the
tags on any terminal, for example in a log that is read by a tool.
See Custom tasks.
release.publish fails to authenticate¶
release.publish passes the PYPI_TOKEN (TEST_PYPI_TOKEN with --test-pypi, and
UV_PUBLISH_TOKEN without it) environment variable to uv publish. Without a token it only works
in GitHub Actions with the id-token: write permission (Trusted Publishing); anywhere else it stops
with a clear message. Make sure the variable is set (e.g. as a CI secret) before running it:
export PYPI_TOKEN=pypi-...
invoke release.publish
export TEST_PYPI_TOKEN=pypi-...
invoke release.publish --test-pypi
See Release.
fix-python / fix-docstrings / fix-shell changed files I didn't expect¶
fix_* tasks modify files in place by design (see the
naming convention). Always run them on a clean working tree so the
diff is easy to review:
git status # make sure everything is committed first
invoke format.fix-python
git diff # review what changed
My custom paths aren't picked up¶
Only paths.* keys you explicitly set in invoke.yaml are used; unset ones fall back to their
default, which is derived from other keys, not from a previous override. For example, setting
paths.tests also moves the default for paths.unit_tests (since it's derived from paths.tests),
but setting paths.unit_tests alone does not affect paths.tests. See
Config → Overriding Paths for a worked example.
Where do I ask for help / report a bug?¶
Open an issue on GitHub. See the developer guide if you'd like to contribute a fix.