Skip to content
This repository


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

python taskwarrior api

branch: develop

taskw - Python API for the taskwarrior DB

This is a python API for the taskwarrior command line tool.

It contains two implementations: taskw.TaskWarriorShellout and taskw.TaskWarriorDirect. The first implementation is the supported one recommended by the upstream taskwarrior core project. It uses the task export and task import commands to manipulate the task database. The second implementation opens the task db file itself and directly manipulates it. It exists for backwards compatibility, but should only be used when necessary.

Build Status

Branch Status
master Build Status - master branch
develop Build Status - develop branch

Getting taskw


Using taskw requires that you first install taskwarrior.

Installing it from is easy with pip:

$ pip install taskw

The Source

You can find the source on github at


Looking at tasks

>>> from taskw import TaskWarrior
>>> w = TaskWarrior()
>>> tasks = w.load_tasks()
>>> tasks.keys()
['completed', 'pending']
>>> type(tasks['pending'])
<type 'list'>
>>> type(tasks['pending'][0])
<type 'dict'>

Adding tasks

>>> from taskw import TaskWarrior
>>> w = TaskWarrior()
>>> w.task_add("Eat food")
>>> w.task_add("Take a nap", priority="H", project="life", due="1359090000")

Completing tasks

>>> from taskw import TaskWarrior
>>> w = TaskWarrior()
>>> w.task_done(46)

Being Flexible

You can point taskw at different taskwarrior databases.

>>> from taskw import TaskWarrior
>>> w = TaskWarrior(config_filename="~/some_project/.taskrc")
>>> w.task_add("Use 'taskw'.")

Looking at the config

>>> from taskw import TaskWarrior
>>> w = TaskWarrior()
>>> config = w.load_config()
>>> config['data']['location']
>>> config['_forcecolor']

Using Python-appropriate Types (Dates, UUIDs, etc)

>>> from taskw import TaskWarrior
>>> w = TaskWarrior(marshal=True)
>>> w.get_task(id=10)
  'description': 'Hello there!',
  'entry': datetime.datetime(2014, 3, 14, 14, 18, 40, tzinfo=tzutc())
  'id': 10,
  'project': 'Saying Hello',
  'status': 'pending',
  'uuid': UUID('4882751a-3966-4439-9675-948b1152895c')
Something went wrong with that request. Please try again.