Skip to content


Actions Status Actions Status Coverage Status

What is Pydo?

pydo is a free software command line task manager built in Python.

Why another CLI Task Manager?

Taskwarrior has been the gold standard for CLI task managers so far. However, It has the following inconveniences:

  • It uses a plaintext file as data storage.
  • It stores the data in a non standard way in different files.
  • It's written in C, which I don't speak.
  • It's development has come to code maintenance only.
  • There are many issues with how it handles recurrence.
  • It doesn't have friendly task identifiers.
  • There is no way of accessing the task time tracking from the python library.

And lacks the following features:

  • Native Kanban or Scrum support.
  • Task estimations.
  • Easy report creation.
  • Easy way to manage the split of a task in subtasks.
  • Freezing of recurrent tasks.

Most of the above points can be addressed through the Taskwarrior plugin system or udas, but sometimes it's difficult to access the data or as the database grows, the performance drops so quick that it makes them unusable.

tasklite is a promising project that tackles most of the points above. But as it's written in Haskel, I won't be able to add support for the features I need.

A quick demonstration

Let's see pydo in action. We'll first add three tasks to our list.

$: pydo add Buy milk
  [+] Added task 0: Buy milk
$: pydo add Buy eggs
  [+] Added task 1: Buy eggs
$: pydo add Bake cake
  [+] Added task 2: Bake cake

Now let's see the list.

$: pydo list
  ID │ Description
  0  │ Buy milk
  1  │ Buy eggs
  2  │ Bake cake

Suppose we bought our ingredients and wish to mark the first two tasks as done.

$: pydo do 0 1
  [+] Closed task 0: Buy milk with state done
  [+] Closed task 1: Buy eggs with state done

$: pydo list
  ID │ Description
  2  │ Bake cake

Those are the first three features, the add, list and done commands, but they represent all you need to know, to get started with pydo.

But there are hundreds of other features, so if you learn more, you can do more. It's entirely up to you to choose how you use pydo. Stick to the three commands above, or learn about sophisticated agile support, custom reports, user defined metadata and more.


To install pydo, run:

pip install py-do

The installation method will create a new pydo database at ~/.local/share/pydo/database.tinydb.

pydo reads it's configuration from the yaml file located at ~/.local/share/pydo/config.yaml. The default template is provided at installation time.

What's next?

Probably the most important next step is to start using pydo. Capture your tasks, don't try to remember them. Review your task list to keep it current. Consult your task list to guide your actions. Develop the habit.

It doesn't take long until you realize that you might want to change your workflow. Perhaps you are missing due dates, and need more defined deadlines. Perhaps you need to make greater use of tags to help you filter tasks differently. You'll know if your workflow is not helping you as much as it could.

This is when you might look closer at the docs and the recommended Best Practices.

If you want to contribute to the project follow this guidelines.

Welcome to pydo.


As most open sourced programs, pydo is standing on the shoulders of giants, namely:

Testing framework, enhanced by the awesome pytest-cases library that made the parametrization of the tests a lovely experience.
Python static type checker.
Python linter with lots of checks.
Python formatter to keep a nice style without effort.
Python formatter to automatically fix wrong import statements.
Python formatter to order the import statements.
Command line tool to manage the dependencies.
To build this documentation site, with the Material theme.
To check the installed dependencies for known security vulnerabilities.
To finds common security issues in Python code.
YAML fixer.


For guidance on setting up a development environment, and how to make a contribution to pydo, see Contributing to pydo.

Last update: 2021-10-08