Installing Taskwarrior

Documentation
1

Installing Taskwarrior

Overview

Taskwarrior is a command-line task manager. WingTask provides a
TaskChampion sync server that Taskwarrior can use to keep your tasks in
sync across devices.

Installing Taskwarrior is not required to use WingTask. You can manage
all your tasks through the WingTask web interface without it.

If you want to use Taskwarrior alongside WingTask — for example, to add
or complete tasks from a terminal — this page explains how to install it
and connect it to WingTask’s sync server.

Installing Taskwarrior

Option 1: Package Manager

macOS

brew install task

Debian/Ubuntu

sudo apt install taskwarrior

Fedora/RHEL

sudo dnf install task

Arch Linux

sudo pacman -S task

FreeBSD

pkg install taskwarrior

Note: Package manager versions may lag behind the latest release.
Check task --version after installing.

Option 2: Build from Source

Prerequisites

# Debian/Ubuntu
sudo apt install cmake make g++ libgnutls28-dev libuuid1 uuid-dev

# macOS (via Homebrew)
brew install cmake

# Rust toolchain (required, MSRV 1.81.0)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Build and install

git clone https://github.com/GothenburgBitFactory/taskwarrior.git
cd taskwarrior

cmake -S . -B build -DCMAKE_BUILD_TYPE=RelWithDebInfo
cmake --build build -j$(nproc)

# Install system-wide (default: /usr/local)
sudo cmake --install build

# Or install to a custom prefix
cmake --install build --prefix ~/.local

Verify the build

task --version

Option 3: Prebuilt Binaries

Download from the
official releases page.
Extract and place the task binary somewhere in your $PATH.

First-Time Setup

After installation, Taskwarrior initializes on first run:

task
# → Creates ~/.task/ data directory on first invocation
# → Prompts to confirm data location

The default data directory is ~/.task/. Configuration lives at
~/.taskrc.

Verify everything works:

task add Buy milk
task list
task 1 done

Syncing with WingTask

WingTask provides a TaskChampion sync server. To connect Taskwarrior to
it, configure the following settings in ~/.taskrc. You can find your
client ID and encryption secret in your WingTask account settings.

task config sync.server.url https://your-sync-server/
task config sync.server.client_id YOUR_CLIENT_ID
task config sync.server.encryption_secret YOUR_ENCRYPTION_SECRET
task sync

Once configured, running task sync will push and pull tasks between
Taskwarrior and WingTask.

Troubleshooting

Problem Fix
task: command not found Add install prefix to $PATH (e.g., ~/.local/bin)
Rust build errors Run rustup update — MSRV is 1.81.0
CMake version too old Requires CMake 3.24+; upgrade via pip install cmake or Homebrew
libuuid missing on Linux sudo apt install uuid-dev
Permission denied on install Use sudo cmake --install build or install to ~/.local

task diagnostics

Run this first when something isn’t working:

task diagnostics

What it reports:

Section What it tells you
Platform / Compiler OS name, compiler version, C++ compliance level
Build Features Git commit hash, CMake version, build type
Configuration Path to ~/.taskrc, data.location, env var overrides
Hooks Which hooks are active or inactive
Tests Broken dependency references, orphaned recurrence UUIDs

Common things it catches:

  • ~/.taskrc is missing or has wrong permissions
  • data.location points to a directory that doesn’t exist
  • A hook script exists but isn’t executable (chmod +x fixes it)
  • A hook has an unrecognized name (must start with on-add,
    on-modify, on-launch, or on-exit)
  • Tasks with dependencies on deleted tasks (broken refs)
  • $TASKDATA or $TASKRC set in your shell environment, silently
    overriding your config

When filing a bug report with the Taskwarrior project, include the
output of task diagnostics — it answers the questions maintainers
always ask first.

Related Topics

Documentation Index