Quickstart - Nuvom
Author: Nahom Zewdu
Description: Lightweight, plugin-first Python task queue — no Redis required.

Skip to content

# Quickstart

This guide walks you through installing Nuvom, defining your first task, and running workers — all in under 5 minutes.

## 🔧 Installation

Nuvom is under active development. Until the first stable release, install it from source:

    git clone https://github.com/nahom-zewdu/Nuvom
    cd Nuvom
    pip install -e .
    ````

    If you plan to contribute or run the documentation:

    ```bash
    hatch shell

This will install all development and documentation dependencies inside a Hatch-managed environment.

## 1. Define a Task

Tasks are regular Python functions decorated with `@task`:

    # tasks.py
    from nuvom.task import task

    @task(retries=2, retry_delay_secs=5, timeout_secs=3, store_result=True)
    def add(x, y):
        return x + y

The decorator enables retry logic, timeouts, and lets you dispatch with `.delay()` or `.map()`.

## 2. Discover Tasks (Optional but Recommended)

Nuvom uses static AST-based discovery to find task definitions without executing your code.

Run once:

    nuvom discover tasks

This generates `.nuvom/manifest.json` to speed up worker startup and avoid runtime imports.

## 3. Submit a Job

Dispatch jobs programmatically:

    from tasks import add

    job = add.delay(5, 7)
    print(job.id)

## 4. Run a Worker

Workers execute jobs in parallel threads:

    nuvom runworker

You can configure worker behavior (e.g., count, batch size) via `.env`. See Configuration for full details.

## 5. Inspect Job Status

    nuvom inspect job <job_id>

This shows result, error, traceback, retries remaining, and timestamps.

To view recent jobs:

    nuvom history recent --limit 10

## 6. Retry Failed Jobs

Retry manually from Python:

    from nuvom.sdk import retry_job

    retry_job("<job_id>")

CLI support for retrying is coming soon.

July 16, 2025