Skip to main content

tasks runner for python projects

Project description

the complementary task runner for python poetry projects

pypi ci

All Contributors


Every development pipeline has tasks, such as test, lint or publish. With taskipy, you can define those tasks in one file and run them with a simple command.

For instance, instead of running the following command:

python -m unittest tests/test_*.py

You can create a task called test and simply run:

poetry run task test

In addition, you can compose tasks and group them together, and also create dependencies between them.

This project is heavily inspired by npm's run script command.


Python 3.6 or newer.

Your project directory should include a valid pyproject.toml file, as specified in PEP-518.



To install taskipy as a dev dependency, simply run:

poetry add --dev taskipy

Adding Tasks

In your pyproject.toml file, add a new section called [tool.taskipy.tasks].

The section is a key-value map, from the names of the task to the actual command that should be run in the shell.



test = "python -m unittest tests/test_*.py"
lint = "pylint tests taskipy"

Running Tasks

In order to run a task, run the following command in your terminal:

$ poetry run task test

You can also list all existing tasks by running the following:

$ poetry run task --list
test                python -m unittest tests/test_*.py
lint                pylint tests taskipy

Passing Command Line Args to Tasks

If you want to pass command line arguments to tasks (positional or named), simply append them to the end of the task command.

For example, running the above task like this:

poetry run task test -h

Is equivalent to running:

python -m unittest tests/test_*.py -h

And will show unittest's help instead of actually running it.

⚠️ Note: if you are using pre \ post hooks, do notice that arguments are not passed to them, only to the task itself.

Composing Tasks

Grouping Subtasks Together

Some tasks are composed of multiple subtasks. Instead of writing plain shell commands and stringing them together, you can break them down into multiple subtasks:

lint_pylint = "pylint tests taskipy"
lint_mypy = "mypy tests taskipy"

And then create a composite task:

lint = "task lint_pylint && task lint_mypy"
lint_pylint = "pylint tests taskipy"
lint_mypy = "mypy tests taskipy"

Pre Task Hook

Tasks might also depend on one another. For example, tests might require some binaries to be built. Take the two following commands, for instance:

test = "python -m unittest tests/test_*.py"
build = "make ."

You could make tests depend on building, by using the pretask hook:

pre_test = "task build"
test = "python -m unittest tests/test_*.py"
build = "make ."

The pretask hook looks for pre_<task_name> task for a given task_name. It will run it before running the task itself. If the pretask fails, then taskipy will exit without running the task itself.

Post Task Hook

From time to time, you might want to run a task in conjuction with another. For example, you might want to run linting after a successful test run. Take the two following commands, for instance:

test = "python -m unittest tests/test_*.py"
lint = "pylint tests taskipy"

You could make tests trigger linting, by using the posttask hook:

test = "python -m unittest tests/test_*.py"
post_test = "task lint"
lint = "pylint tests taskipy"

The posttask hook looks for post_<task_name> task for a given task_name. It will run it after running the task itself. If the task failed, then taskipy will not run the posttask hook.

Using Taskipy Without Poetry

Taskipy was created with poetry projects in mind, but actually only requires a valid pyproject.toml file in your project's directory. As a result, you can use it even eithout poetry:

Installing With PIP

Install taskipy on your machine or in your virtualenv using:

pip install taskipy

Running Tasks

Head into your project's directory (don't forget to activate virtualenv if you're using one), and run the following command:

task TASK

Where TASK is the name of your task.

Advanced Use Cases

If you have a more specific use case, you might not be the first to run into it! Head over to the ADVANCED_FEATURES doc, and look it up.

Maintainers 🚧

Roy Sommer

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Eugene Triguba




Bernardas Ališauskas


This project follows the all-contributors specification. Contributions of any kind welcome!

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for taskipy, version 1.6.0
Filename, size File type Python version Upload date Hashes
Filename, size taskipy-1.6.0-py3-none-any.whl (8.3 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size taskipy-1.6.0.tar.gz (8.1 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page