Getting Started with Celery on KubeMQ

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:

docker run -d \  --name kubemq \  -p 50000:50000 \  -p 9090:9090 \  -e KUBEMQ_TOKEN=YOUR_LICENSE_KEY \  europe-docker.pkg.dev/kubemq/images/kubemq:next

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.

Install kubemq-celery

Install the package with pip or uv:

# pip
pip install kubemq-celery

# uv (recommended)
uv add kubemq-celery

This pulls in celery >= 5.4 and kombu >= 5.4 as dependencies.

Create tasks.py

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.

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

Start a worker

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

celery -A tasks worker --loglevel=info

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

[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.

Send a task

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

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:

[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://.

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.

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:

from tasks import add

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

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:

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:

docker compose logs -f worker-default

Tear everything down with docker compose down when you are finished.

Next Steps