Vikunja¶

What it is¶

Vikunja is an open-source, self-hosted To-do list application that allows you to organize all your tasks on all platforms. As of May 2026, v2.3.0 is the current stable release, featuring a new plugin system, OAuth 2.0 provider capabilities, and enhanced Gantt charts.

What problem it solves¶

Maintaining a consistent task list across devices while maintaining privacy can be challenging with commercial tools. Vikunja provides an enterprise-grade task management experience that you can host yourself, ensuring your data remains private while offering the flexibility to manage everything from simple groceries to complex project timelines.

Where it fits in the stack¶

Category: Services / Task Management. It serves as the operational coordination layer, managing actionable items and deadlines that result from higher-level knowledge and planning.

Typical use cases¶

Personal Task Management: Using the web or mobile interface to track daily chores, shopping lists, and reminders.
Project Planning: Utilizing Gantt charts and Kanban boards to visualize multi-stage projects with dependencies.
Automated Ingestion: Creating tasks automatically via API from emails, chat messages, or CI/CD pipelines.
Collaborative Lists: Sharing specific task lists with family members or team colleagues for joint coordination.
Self-Hosted Productivity Hub: Acting as an OAuth 2.0 provider to allow other self-hosted apps to authenticate users.

Strengths¶

Multiple Views: Seamlessly switch between List, Kanban, Gantt, and Table views for the same set of tasks.
Task Relations: Robust support for subtasks, dependencies (blocking/blocked by), and related tasks.
Rich Filtering: A powerful query language for creating smart views based on tags, dates, and priorities.
Plugin System: Uses the yaegi loader (v2.3.0+) for easy, source-based extensions without recompilation.
OAuth 2.0 Provider: Can act as a central identity provider for other tools in your homelab.
Real-time Collaboration: WebSockets-powered notifications ensure instant updates across clients.
Universal Import: Dedicated migrators for Trello, Todoist, TickTick, WeKan, and a generic CSV mapper.

Limitations¶

Mobile App State: While the PWA is excellent, the native mobile apps are still in active development and may lack some advanced features.
Feature Density: The sheer number of features (relations, namespaces, teams) can be overwhelming for users seeking a simple checklist.
Resource Usage: Requires a database (Postgres/MySQL) and an API backend, making it heavier than "flat-file" task managers.

When to use it¶

When you need a powerful, self-hosted To-do list with support for Kanban boards, Gantt charts, and list views.
For managing complex personal tasks with subtasks, labels, and relations.
When you want a task manager that is accessible via web, desktop, and mobile (via PWA or third-party apps).
When migrating from proprietary tools and requiring a flexible CSV import or dedicated migrator.

When not to use it¶

If you only need a very simple, single-list checklist (Vikunja might have more features than you need).
If you are looking for a full project management suite with deep resource allocation and financial tracking.

Getting started¶

Docker¶

To get Vikunja up and running quickly with Docker:

docker run -p 3456:3456 -v $PWD/files:/app/vikunja/files -v $PWD/db:/db vikunja/vikunja

Hello World¶

Navigate to http://localhost:3456 to access the web interface.
Create your first account (the first user created is an admin by default).
Create your first Project and add a Task to see Vikunja in action.

CLI examples¶

When running in Docker, execute commands using docker exec:

# List all registered users
docker exec <container_name> /app/vikunja/vikunja user list

# Create a new user from the command line
docker exec <container_name> /app/vikunja/vikunja user create --username newuser --email user@example.com --password secret

# Create a full dump (backup) of the database and files
docker exec <container_name> /app/vikunja/vikunja dump

# Run a series of diagnostic checks
docker exec <container_name> /app/vikunja/vikunja doctor

# Manage plugins (v2.3.0+)
docker exec <container_name> /app/vikunja/vikunja plugins list

API examples¶

Vikunja provides a comprehensive REST API. Authenticate using an API token or a Bearer token in the Authorization header.

Python: Quick Entry¶

import requests

# Configuration
URL = "http://localhost:3456/api/v1/tasks"
TOKEN = "YOUR_API_TOKEN"

def quick_add_task(title, description=""):
    headers = {"Authorization": f"Bearer {TOKEN}"}
    data = {
        "title": title,
        "description": description,
        "priority": 3 # High
    }
    response = requests.put(url, headers=headers, json=data)
    return response.json()

print(quick_add_task("Audit homelab services", "Quarterly freshness audit for Batch 99"))

curl: Fetching Projects¶

curl -H "Authorization: Bearer <your_api_token>" \
     "http://localhost:3456/api/v1/projects"

Task Relations¶

Vikunja allows linking tasks together with various relation types.

Available Relation Types¶

Type	Description	Opposite
Subtask	The task is a subtask of another.	Parent task
Parent task	The task is a parent of another.	Subtask
Blocking	The task blocks another task.	Blocked by
Blocked by	The task is blocked by another.	Blocking
Precedes	The task comes before another.	Follows
Follows	The task comes after another.	Precedes
Related	Tasks are related (symmetric).	Related
Duplicate of	The task is a duplicate of another.	Duplicates
Duplicates	The task duplicates another.	Duplicate of
Copied from	The task was copied from another.	Copied to
Copied to	The task was copied to another.	Copied from

SSO, OIDC & OAuth 2.0¶

Vikunja supports OIDC for login and can act as an OAuth 2.0 provider.

OIDC Configuration (Authentik)¶

Add the following to your config.yml:

auth:
  openid:
    enabled: true
    providers:
      authentik:
        name: "Authentik"
        authurl: "https://authentik.example.com/application/o/vikunja/"
        clientid: "<Your Client ID>"
        clientsecret: "<Your Client Secret>"
        scope: "openid profile email"

OAuth 2.0 Provider (v2.3.0+)¶

Vikunja can now issue tokens for other applications. Manage your registered OAuth 2.0 applications in Settings > API Tokens.

CalDAV Synchronization¶

Vikunja supports CalDAV for syncing tasks with external clients or servers like Radicale.

Authentication¶

Use your Vikunja username and: - Account Password: For local or LDAP accounts without 2FA. - CalDAV Token: For OIDC accounts or accounts with 2FA enabled (generate in Settings > CalDAV).

Syncing with Radicale via vdirsyncer¶

To synchronize Vikunja tasks with a Radicale server, use vdirsyncer:

[general]
status_path = "~/.vdirsyncer/status/"

[pair vikunja_radicale]
a = "vikunja"
b = "radicale"
collections = ["from a", "from b"]
metadata = ["displayname", "color"]

[storage vikunja]
type = "caldav"
url = "https://vikunja.example.com/dav/principals/<username>/"
username = "<username>"
password = "<password_or_token>"

[storage radicale]
type = "caldav"
url = "https://radicale.example.com/<username>/"
username = "<username>"
password = "<password>"

Radicale — For CalDAV sync of tasks.
Synapse — For notifications and communication.
Habitica — For gamified task management.
Focalboard — For an alternative Kanban-focused tool.
Nextcloud — For tasks integrated into a larger suite.
Authentik — For managing Vikunja SSO/OIDC.
n8n — For automating task creation from emails or chats.
Mealie — For meal-related tasks and recipe integration.
Paperless-ngx — For linking tasks to archived documents.
Immich — For managing media assets referenced in tasks.
Actual Budget — For financial tasks and budget-related checklists.
Email-to-Calendar — Complementary playbook for scheduling.
Vikunja Task Routing — LLM patterns for automated task classification.

Vikunja¶

What it is¶

What problem it solves¶

Where it fits in the stack¶

Typical use cases¶

Strengths¶

Limitations¶

When to use it¶

When not to use it¶

Getting started¶

Docker¶

Hello World¶

CLI examples¶

API examples¶

Python: Quick Entry¶

curl: Fetching Projects¶

Task Relations¶

Available Relation Types¶

SSO, OIDC & OAuth 2.0¶

OIDC Configuration (Authentik)¶

OAuth 2.0 Provider (v2.3.0+)¶

CalDAV Synchronization¶

Authentication¶

Syncing with Radicale via vdirsyncer¶

Sources / References¶

Backlog¶

Contribution Metadata¶

Vikunja¶

What it is¶

What problem it solves¶

Where it fits in the stack¶

Typical use cases¶

Strengths¶

Limitations¶

When to use it¶

When not to use it¶

Getting started¶

Docker¶

Hello World¶

CLI examples¶

API examples¶

Python: Quick Entry¶

curl: Fetching Projects¶

Task Relations¶

Available Relation Types¶

SSO, OIDC & OAuth 2.0¶

OIDC Configuration (Authentik)¶

OAuth 2.0 Provider (v2.3.0+)¶

CalDAV Synchronization¶

Authentication¶

Syncing with Radicale via vdirsyncer¶

Related tools / concepts¶

Sources / References¶

Backlog¶

Contribution Metadata¶