Forbes Guthrie edited this page Feb 4, 2017 · 23 revisions

User Documentation


If you don't use the package for your distribution, you can still run QTodoTxt without installation but you will need to install manually two things: python and pyside.

To install on Linux:

  • Install PySide (in Ubuntu: sudo apt-get install python3-pyside)

and additionally, if qtodotxt version >= 1.6:

  • Install PyQt5 (in Ubuntu: sudo apt-get install python3-pyqt5)
  • Install dateutil (in Ubuntu: sudo apt-get install python3-dateutil)

To install on Windows:

It is also possible to use winpython on windows which come with python and PyQt5

To install on Mac:

The easiest way to install the needed dependencies on a mac is via the command-line package manager homebrew:

  • Update homebrew to get the latest formulae: $ brew update
  • Install the MacOS Command Line Tools package (required because homebrew builds python from source locally): xcode-select --install
  • Install python3: brew install python3
  • Install python bindings for Qt:
    • If qtodotxt version <= 1.5: brew install pyside --with-python3
    • If qtodotxt version >=1.6: brew install pyqt5
  • Install dateutil: pip3 install python-dateutil

If homebrew is not an option for your system, you may wish to take a look at this guide to installing PyQt5 on a mac. Good luck!

Run it !

If you installed QTodoTxt with binary package you have an executable in your path. Just run it.

If you have cloned or downloaded the QTodoTxt source, the easiest way to run QTodoTxt is:

  • On Linux and mac: execute bin/qtodotxt
  • On Windows: execute python bin\qtodotxt.pyw

Alternatively, if QTodoTxt has been installed as a python package, you can run it from the command-line executable:

$ qtodotxt

QTodoTxt can also be run like this, for cases where you really need to specify the python interpreter:

$ python3 -c "import as app;"

Command line arguments support:

  • FILENAME: opens file FILENAME
  • -q or --quickadd: opens the add-task dialog and exits the application when done
  • -l or --loglevel: set one of these logging levels: DEBUG, INFO, WARNING, ERROR, CRITICAL
  • -h or --help: command line help (for more options and details)

Use it!

Useful shortcuts

  • Create Task: Insert, Ctrl+N or Ctrl+I
  • Delete Task: Delete
  • Complete Task: C or X
  • Edit Task: Enter
  • Save List: Ctrl+S
  • Search Tasks: Ctrl+F
  • Increase Task Priority: +
  • Decrease Task Priority: -

Behaviour description

  • Hyperlinks: Are recognized automatically if starting with http://, https://, ftp:// etc.
  • Sorting: Is done automatically at first on priorities and within this order alphabetically
  • Due dates format: due:YYYY-MM-DD (other formats can lead to strange behaviour)
  • Due dates color: red = today or past; orange = within the following week; black = more than one week
  • Threshold dates format: t:YYYY-MM-DD (other formats can lead to strange behaviour). You can show or hide tasks which did not reached their threshold date yet with the option "File -> Preferences -> Hide future tasks".
  • Auto archive: Application only auto-archives items completed while auto-archive option is enabled. Tasks completed during auto-archive option being disabled remain but are displayed using strike trough font.

Task filter

The task filter can handle basic and/or/not conditions. The syntax is as follows:

  • AND-operator: , or (whitespace)
  • OR-operator: |
  • NOT-operator: prefixed ~ or prefixed !

These operators follow the following order of precedence: OR, AND, NOT. So, for example:

  • work job1 | home: Either (matches 'work' AND 'job1') OR (matches 'home')
  • norweigan blue ~dead | !parrot: Either (matches 'norweigan' AND 'blue' AND does NOT match 'dead') OR (does NOT match 'parrot')

Since the python re module is used, most of the escaped regex characters will also work when attached to one of the (comma- or space-delimited) strings. E.g.:

  • \bcleese\b will match 'cleese' but not 'johncleese'
  • 2014-\d\d-07 will match '2014-03-07' but not '2014-ja-07'

The method can handle parentheses in the search strings. Unlike most regex characters, these don't need to be escaped since they are escaped automatically. So the search string (B) will match '(B) nail its feet to the perch'.


  • Distraction-Free Priorities: To focus on a single priority, such as (A) tasks, type (A), A) or (A in the search filter. Clicking on a project or context will now show just the (A) priorities, which is great if you want to focus on your top priorities without distraction. Best part is that the filter criteria remains until you reset it!
  • DropBox Integration: QTodoTxt works well with DropBox and can now reload automatically your todo.txt file to reflect the last changes (even when done outside QTodoTxt).
  • Formatting your tasks: You can use any of the supported HTML subset to format your tasks. For example: <b>Hello</b> <i>QTodoTxt!</i> as a task description will gave you: Hello QTodoTxt!
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.