Getting Started

This guide will get you up and running with django-vtasks in a few minutes.

Installation

Install the core library:

pip install django-vtasks

Or with uv:

uv add django-vtasks

Optional Dependencies

# For Valkey/Redis backend
uv add "django-vtasks[valkey]"

# For Prometheus metrics
uv add "django-vtasks[metrics]"

Quick Configuration

Database Backend (Simplest)

The database backend requires no additional infrastructure - it uses your existing Django database.

# settings.py
INSTALLED_APPS = [
    # ...
    "django_vtasks",
    "django_vtasks.db",  # Required for the Database backend
]

TASKS = {
    "default": {
        "BACKEND": "django_vtasks.backends.db.DatabaseTaskBackend",
    }
}

Run migrations to create the task tables:

python manage.py migrate

Valkey Backend (High Performance)

For high-throughput workloads, use the Valkey backend:

# settings.py
INSTALLED_APPS = [
    # ...
    "django_vtasks",
]

TASKS = {
    "default": {
        "BACKEND": "django_vtasks.backends.valkey.ValkeyTaskBackend",
        "OPTIONS": {
            "BROKER_URL": "valkey://localhost:6379/0",
        }
    }
}

Define Your First Task

Create a tasks.py file in your Django app:

# myapp/tasks.py
from django_vtasks import task

@task
def send_welcome_email(user_id):
    from myapp.models import User
    user = User.objects.get(id=user_id)
    # Your email logic here
    print(f"Sent welcome email to {user.email}")

Enqueue Tasks

Call your task from anywhere in your application:

from myapp.tasks import send_welcome_email

# In a sync view
def register_user(request):
    user = User.objects.create(...)
    send_welcome_email.enqueue(user.id)
    return HttpResponse("User created!")

# In an async view (better performance)
async def register_user_async(request):
    user = await User.objects.acreate(...)
    await send_welcome_email.aenqueue(user.id)
    return HttpResponse("User created!")

Run the Worker

Start a worker to process tasks:

python manage.py runworker

That's it! Your tasks will now be processed in the background.

Next Steps

• Read the Guide for detailed usage patterns (unique tasks, batching, scheduling)
• Check the Configuration reference for all available settings
• Learn about Deployment options for production