Invoke, often referred to as pyinvoke to avoid name collision, is a Python task execution tool and library, drawing inspiration from Make and Rake. It enables users to define shell commands within Python functions and execute them via a command-line interface. The current stable version is 1.0.4, with releases occurring periodically to maintain compatibility and add features.
Install & Compatibility
Where this runs
tested against v3.0.3 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.925 runs
installs and imports cleanly · install 0.0s · import 0.776s · 19MB
glibcpy 3.10–3.925 runs
installs and imports cleanly · install 1.6s · import 0.612s · 19MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
task
✓ from invoke import task
Collection
✓ from invoke import Collection
Used for organizing tasks into namespaces.
Program
✓ from invoke import Program
Used for programmatic execution or custom CLI entry points.
Create a `tasks.py` file in your project directory. Define tasks as Python functions decorated with `@task`, ensuring they accept a `Context` object (conventionally named `c`) as their first argument. Execute tasks from the command line using `invoke <task_name>`.
from invoke import task
@task
def clean(c):
"""Removes build artifacts."""
print("Cleaning up build/ directory...")
# Use '|| true' for robustness in quickstart if 'rm' might fail or not exist
c.run("rm -rf build/ || true")
print("Clean complete.")
@task
def greeting(c, name="World"):
"""Says hello to the given NAME."""
print(f"Hello, {name}!")
@task(aliases=['deploy'])
def push(c):
"""Pushes code to a remote repository (example)."""
print("Simulating deployment...")
# For quickstart, a simple echo is safer than an actual deployment command
c.run("echo 'Deployment simulated!'")
print("Push complete.")
# To run these tasks:
# 1. Save this code as `tasks.py` in your project root.
# 2. Open your terminal in the same directory.
# 3. Run tasks: `invoke clean`, `invoke greeting --name Pythonista`, `invoke deploy`
invoke --version
Debug
Known issues
gotchaThe PyPI package name is `invoke`, not `pyinvoke`. Always use `pip install invoke` for installation.fixUse `pip install invoke` to install the library.
affects: All versions
breakingTask functions now explicitly require a `Context` object as their first argument. Older examples or codebases might omit this, leading to `TypeError`.fixUpdate task definitions to accept a `Context` object, e.g., `@task def my_task(c): ...`.
affects: Invoke 0.13.0 and later
gotchaInvoke 1.x supports both Python 2.7+ and 3.4+. However, future major versions (e.g., Invoke 2.x) are expected to drop Python 2 support. Plan for migration if still using Python 2.fixEnsure your development environment uses Python 3.4+ for forward compatibility. Regularly check Invoke's documentation for upcoming breaking changes related to Python version support.
affects: All 1.x versions
gotchaThe way task arguments are defined and parsed (e.g., short/long flags, default values, types) has evolved. Complex argument parsing might require specific syntax or aliases.fixRefer to the official documentation on task arguments (`docs.pyinvoke.org/en/stable/concepts/tasks.html#argument-parsing`) for the latest and recommended patterns, especially for optional or typed arguments.
affects: All versions (evolutionary changes)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'invoke'
The `invoke` package is not installed in the current Python environment.
fixRun `pip install invoke` to install the library.
NameError: name 'task' is not defined
The `@task` decorator was used in `tasks.py` without being imported from the `invoke` package.
fixAdd `from invoke import task` at the top of your `tasks.py` file.
TypeError: my_task() missing 1 required positional argument: 'c'
A task function was defined without its required `Context` object as the first argument.
fixModify the task function signature to accept a `Context` object, e.g., change `def my_task():` to `def my_task(c):`.
CommandNotFoundError: The command 'your-command-here' was not found. (or FileNotFoundError)
The shell command specified within `c.run()` does not exist or is not in the system's PATH where `invoke` is executed.
fixEnsure the command is correctly installed and accessible in your shell's PATH, or provide the full absolute path to the executable in `c.run()`.
Audit
Dependencies
No dependency data recorded yet.