---
title: "Configuration"
description: "Configuration — Python BabelQueue SDK (1.x)."
source: https://babelqueue.com/docs/babelqueue-python/1.x/configuration/
updated: 2026-06-14T00:00:00.000Z
---

# Configuration

Create a `BabelQueue` runtime and point it at your broker with a URL. The
transport is chosen from the URL scheme — no separate "broker" flag.

## Broker URL

```python
from babelqueue import BabelQueue

# Redis (extra: babelqueue[redis])
app = BabelQueue("redis://localhost:6379/0", queue="orders")

# RabbitMQ (extra: babelqueue[amqp])
# app = BabelQueue("amqp://guest:guest@localhost:5672/", queue="orders")

# Amazon SQS (extra: babelqueue[sqs])
# app = BabelQueue("sqs://eu-central-1", queue="orders")

# Azure Service Bus (extra: babelqueue[azureservicebus])
# app = BabelQueue("sb://<namespace>.servicebus.windows.net", queue="orders")

# Apache Pulsar (extra: babelqueue[pulsar])
# app = BabelQueue("pulsar://localhost:6650", queue="orders")

# Apache Kafka (extra: babelqueue[kafka])
# app = BabelQueue("kafka://localhost:9092", queue="orders")

# Apache ActiveMQ Artemis (extra: babelqueue[artemis])
# app = BabelQueue("artemis://localhost:5672", queue="orders")

# In-process, great for tests/local — no broker required
# app = BabelQueue("memory://", queue="orders")
```

| Scheme      | Transport                      | Requires            |
| ----------- | ------------------------------ | ------------------- |
| `memory://` | In-process (tests / local)     | built in            |
| `redis://`  | Redis (reliable-queue pattern) | `babelqueue[redis]` |
| `amqp://`   | RabbitMQ (via `pika`)          | `babelqueue[amqp]`  |
| `sqs://`    | Amazon SQS (via `boto3`)       | `babelqueue[sqs]`   |
| `sb://`     | Azure Service Bus (via `azure-servicebus`) | `babelqueue[azureservicebus]` |
| `pulsar://` | Apache Pulsar (via `pulsar-client`) | `babelqueue[pulsar]` |
| `kafka://`  | Apache Kafka (via `confluent-kafka`) | `babelqueue[kafka]` |
| `artemis://` | Apache ActiveMQ Artemis (via `python-qpid-proton`) | `babelqueue[artemis]` |

The `sqs://` URL is `sqs://<region>` with optional query params: `endpoint`
(LocalStack/ElasticMQ), `prefix` (a queue-URL prefix that skips `GetQueueUrl`), `fifo=1`,
`group_id`, `wait_time`. The transport sends the canonical envelope with the
[§3 `MessageAttributes`](/docs/spec/1.x/broker-bindings/#amazon-sqs) and reconciles
`attempts` to `ApproximateReceiveCount − 1`.

The `sb://` URL is `sb://<namespace>.servicebus.windows.net` and authenticates with
`DefaultAzureCredential` (Azure AD); pass `connection_string=...` to `AsbTransport` for
SAS auth, or `BabelQueue(transport=...)` with a built client. It maps the envelope onto
native Service Bus fields ([§4](/docs/spec/1.x/broker-bindings/#azure-service-bus)) and
reconciles `attempts` to `max(body, DeliveryCount − 1)`.

The `pulsar://` URL is `pulsar://<host>:<port>` (or `pulsar+ssl://`); pass a built client
via `BabelQueue(transport=...)` for TLS/token auth. It projects the envelope onto native
Pulsar message properties (`bq-job` = URN, plus the `bq-` fields,
[§5](/docs/spec/1.x/broker-bindings/#apache-pulsar)), defaults to a `Shared` subscription
named `babelqueue`, and reconciles `attempts` to `max(body, redelivery_count)` — the
redelivery count is 0-based, so **no −1**.

The `kafka://` URL is `kafka://<host>:<port>[,<host>:<port>]`; pass an injected `producer` +
`consumer_factory` for custom auth. The record value is the envelope, projected onto `bq-`
headers ([§6](/docs/spec/1.x/broker-bindings/#apache-kafka)); consume is **process-then-commit**
(`enable.auto.commit=false`) and `attempts` reconciles to the authoritative `bq-attempts`
header (else the body). Kafka has no native delay/DLQ, so the runtime owns retry by
republishing with attempts+1 and dead-letters to `<queue>.dlq`.

The `artemis://` URL is `artemis://<host>:<port>` (or `artemis+ssl://`) — Apache ActiveMQ
Artemis over **AMQP 1.0** (`python-qpid-proton`, not RabbitMQ's 0-9-1 `pika`); pass a built
connection via `BabelQueue(transport=...)` for auth/TLS. It projects the envelope onto the AMQP
a JMS peer reads — `x-opt-jms-type` = URN, `correlation-id` = `trace_id`, plus the string `bq_`
application properties (underscored — JMS property names must be valid Java identifiers; [§7](/docs/spec/1.x/broker-bindings/#apache-activemq-artemis)) — and
reconciles `attempts` to `max(body, delivery_count)`; the AMQP delivery-count is 0-based, so
**no −1**.

## Options

| Option           | Default   | Description                                              |
| ---------------- | --------- | ------------------------------------------------------- |
| `queue`          | `default` | Queue name written to `meta.queue`                      |
| `max_attempts`   | —         | Retries before a message is exhausted (bumps `attempts`)|
| `dead_letter`    | `False`   | Quarantine exhausted messages on `<queue>.dlq`          |
| `on_unknown_urn` | `fail`    | `fail` \| `delete` \| `release` \| `dead_letter`        |

```python
app = BabelQueue(
    "redis://localhost:6379/0",
    queue="orders",
    max_attempts=3,
    dead_letter=True,
    on_unknown_urn="dead_letter",
)
```

> Need just the wire codec, with no broker wiring? Import `EnvelopeCodec`
> directly — see [Producing messages](/docs/babelqueue-python/1.x/producing-messages/).

Next: [Producing messages](/docs/babelqueue-python/1.x/producing-messages/).