Quickstart

Get started with AsyncMQ in just a few steps: register a task, enqueue a job, and launch a worker.

1. Register a Task

Apply the @task decorator to an async function, which does not automatically enqueue jobs on invocation—instead, it:

1. Wraps your function so workers know how to execute it.
2. Adds an enqueue helper method to schedule jobs.
3. Stores task metadata (queue, retries, TTL, etc.) in TASK_REGISTRY.

Create your backend (Redis as default)

from asyncmq.backends.redis import RedisBackend
from asyncmq.logging import logger
from asyncmq.tasks import task

backend = RedisBackend()

@task(queue="default")
async def say_hello(name: str):
    logger.info(f"👋 Hello, {name}!")

Warning

Calling say_hello("World") executes the function immediately, without enqueuing. To schedule a background job, you must use say_hello.enqueue(...).

2. Enqueue a Job (delay)

Use the generated enqueue helper on your task. All optional parameters have sensible defaults:

• delay=0
• priority=5
• depends_on=None
• repeat_every=None
• backend is optional, you can pass here the instance or it will load the default from the settings.

# app.py (continued)
import anyio


async def main():
    # This schedules your function to run on a worker, it does NOT execute it immediately:
    await say_hello.enqueue(
        "World"
    )
    print("Job enqueued to 'default' queue.")

if __name__ == "__main__":
    anyio.run(main)

Run it:

python app.py

Enqueue a Job

Use the generated enqueue helper on your task. All optional parameters have sensible defaults:

• delay=0
• priority=5
• depends_on=None
• repeat_every=None

# app.py (continued)
async def main():
    # Enqueue a job; this helper returns None
    await say_hello.enqueue(backend, "World")
    print("Job enqueued to 'default' queue.")

if __name__ == "__main__":
    asyncio.run(main())

Run it:

python app.py

3. Inspect Jobs with the CLI

Peek at pending and completed jobs:

• List waiting (pending) jobs asyncmq job list --queue default --state waiting

asyncmq job list --queue default --state waiting

• List completed jobs asyncmq job list --queue default --state completed

asyncmq job list --queue default --state completed

4. Launch a Worker

Start a worker to process tasks from the default queue:

# Default concurrency (1) and backend (from settings or Redis)
asyncmq worker start default

# Override concurrency
asyncmq worker start default --concurrency 2

You should see output like:

[INFO] Starting worker for queue 'default' with concurrency=1

---

Congratulations, your first AsyncMQ task is live!

Next: Core Concepts & Architecture to explore queues, jobs, workers, and storage backends in depth.