# Getting Started with Celery on KubeMQ (/integrations/celery/tutorials/getting-started)



`kubemq-celery` is the KubeMQ transport and result backend for [Celery](https://docs.celeryq.dev/). Point your Celery app at a `kubemq://` broker URL and KubeMQ becomes a drop-in replacement for Redis or RabbitMQ — with native gRPC acknowledgment, server-side delayed delivery, and an optional result backend that needs no external database.

This guide takes you from an empty directory to a running worker executing tasks in about five minutes.

## Quick start [#quick-start]

<Steps>
  <Step>
    ### Prerequisites [#prerequisites]

    You need:

    * **Python 3.10 or newer**
    * A **KubeMQ broker** running and reachable (default: `localhost:50000`)

    The fastest way to get a broker is Docker:

    <RunKubeMQ ports="[50000, 9090]" />

    Port `50000` is the gRPC port the transport connects to. Port `9090` is the shared HTTP server (REST and the `/health` probe) — `curl http://localhost:9090/health` confirms the broker is up as tasks flow through.
  </Step>

  <Step>
    ### Install kubemq-celery [#install-kubemq-celery]

    Install the package with `pip` or [uv](https://docs.astral.sh/uv/):

    ```bash
    # pip
    pip install kubemq-celery

    # uv (recommended)
    uv add kubemq-celery
    ```

    This pulls in `celery >= 5.4` and `kombu >= 5.4` as dependencies.
  </Step>

  <Step>
    ### Create tasks.py [#create-taskspy]

    Create a file called `tasks.py`. The key line is `import kubemq_celery` — importing the package registers the `kubemq://` URL scheme with Kombu's transport registry, which makes the broker URL valid.

    ```python title="tasks.py"
    import kubemq_celery  # registers the kubemq:// transport
    from celery import Celery

    app = Celery("myapp", broker="kubemq://localhost:50000")


    @app.task
    def add(x, y):
        return x + y
    ```

    <Callout type="warn">
      `import kubemq_celery` **must** run before Celery uses the broker URL. The import is what registers the `kubemq://` scheme — without it Celery raises `ValueError: Unknown transport 'kubemq'`. Keep the import at the top of your app module, even if your editor flags it as unused.
    </Callout>
  </Step>

  <Step>
    ### Start a worker [#start-a-worker]

    Start a Celery worker that loads the app from `tasks.py`:

    ```bash
    celery -A tasks worker --loglevel=info
    ```

    On boot you should see the broker URL, the queues the worker is consuming, and a "ready" line:

    ```text
    [config]
    .> broker:      kubemq://localhost:50000
    .> results:     disabled://

    [queues]
    .> celery       exchange=celery(direct) key=celery

    [2026-04-03 12:00:00,000: INFO/MainProcess] Connected to kubemq://localhost:50000
    [2026-04-03 12:00:00,100: INFO/MainProcess] celery@hostname ready.
    ```

    The `results: disabled://` line is expected — you have not configured a result backend yet. You will enable it in step 6. Leave this worker running.
  </Step>

  <Step>
    ### Send a task [#send-a-task]

    Open a Python shell (or a second script) in the same directory and dispatch a task with `.delay()`:

    ```python
    from tasks import add

    result = add.delay(4, 6)
    print(f"Task ID: {result.id}")
    ```

    Switch to the worker terminal. You should see the task arrive and complete:

    ```text
    [2026-04-03 12:00:05,000: INFO/MainProcess] Task tasks.add[abc123] received
    [2026-04-03 12:00:05,010: INFO/MainProcess] Task tasks.add[abc123] succeeded in 0.01s: 10
    ```

    The worker received the message over gRPC, executed `add(4, 6)`, and acknowledged it. At this point the result is computed but not stored anywhere — `result.get()` would block, because the backend is still `disabled://`.
  </Step>

  <Step>
    ### Enable the result backend [#enable-the-result-backend]

    To retrieve task return values, set a `result_backend`. KubeMQ ships a queue-peek backend that stores results as KubeMQ Queue messages — no external Redis or database required.

    ```python title="tasks.py"
    import kubemq_celery
    from celery import Celery

    app = Celery(
        "myapp",
        broker="kubemq://localhost:50000",
        result_backend="kubemq://localhost:50000",
    )


    @app.task
    def add(x, y):
        return x + y
    ```

    Restart the worker so it picks up the new configuration, then dispatch a task and block on the result:

    ```python
    from tasks import add

    result = add.delay(4, 6)
    print(result.get(timeout=10))  # Output: 10
    ```

    <Callout type="info">
      The result backend retrieves results with KubeMQ's non-destructive `peek_queue_messages()`. Because the peek does not consume the message, multiple callers can read the same result independently — handy when several services need the output of one task.
    </Callout>
  </Step>

  <Step>
    ### One-command quickstart with Docker Compose [#one-command-quickstart-with-docker-compose]

    If you would rather not install anything locally, the repository ships a Docker Compose file that brings up a KubeMQ broker and Celery workers together:

    ```bash
    cd examples/kubernetes
    docker compose up -d
    ```

    This starts:

    * A **KubeMQ broker** on port `50000` (shared HTTP server, REST/health on `9090`)
    * One or more **Celery workers** connected to the broker via `CELERY_BROKER_URL=kubemq://kubemq:50000`

    Watch a worker's logs to confirm it connected and is consuming tasks:

    ```bash
    docker compose logs -f worker-default
    ```

    Tear everything down with `docker compose down` when you are finished.
  </Step>

  <Step>
    ### Next Steps [#next-steps]

    <Cards>
      <Card title="Concepts" href="/integrations/celery/concepts" description="How the kubemq:// transport maps Celery queues, acks, and delays onto KubeMQ." />

      <Card title="Configuration" href="/integrations/celery/how-to/configuration" description="Transport options, TLS, result backend settings, and DLQ tuning." />

      <Card title="Canvas Workflows" href="/integrations/celery/how-to/canvas-workflows" description="Chains, groups, chords, and other Celery canvas primitives on KubeMQ." />

      <Card title="Migration Guide" href="/integrations/celery/how-to/migration" description="Switch an existing app from Redis or RabbitMQ to KubeMQ." />
    </Cards>
  </Step>
</Steps>