What Prefetch Controls
Without any QoS setting, RabbitMQ will push messages to a consumer as fast as the network allows, regardless of how quickly that consumer is actually acknowledging them, because the default prefetch count is unlimited (0). This means a single slow consumer can end up holding thousands of unacknowledged messages in its local buffer while other idle consumers on the same queue starve, since RabbitMQ has already committed those messages to the busy one. basic.qos(prefetch_count=N) caps how many unacknowledged messages the broker will deliver to a given consumer at once, forcing it to ack (or nack) before receiving more, which directly controls the balance between per-consumer throughput and even distribution across a worker pool.
Cricket analogy: It is like a captain handing the new ball to a fast bowler for an unlimited number of overs before rotating the attack — without a cap, one bowler tires while others warming up in the deep never get a turn, exactly like an unbounded prefetch starving idle consumers.
Setting Prefetch and Choosing a Value
Prefetch is set per-channel with basic.qos before consuming begins, and in RabbitMQ 3.3+ it applies per-consumer on that channel by default rather than shared across the whole channel. A prefetch of 1 gives maximum fairness — each consumer only gets a new message after acking the last — which is ideal for long-running, variable-duration jobs like video transcoding where you don't want one worker hoarding a backlog while another sits idle. For short, uniform tasks like simple validation or logging, a low prefetch adds unnecessary network round-trip latency between broker and consumer; a higher value (10-100) lets messages stream continuously and dramatically improves throughput, at the cost of a slower rebalance if that consumer crashes with unacked messages still on it.
Cricket analogy: It is like a bowling captain giving a death-overs specialist exactly one over at a time before reassessing match situation, versus handing a spinner a long unbroken spell during a quiet middle phase — prefetch=1 versus a higher batch depends entirely on the nature of the task.
channel.basic_qos(prefetch_count=10) # up to 10 unacked messages per consumer
def callback(ch, method, properties, body):
try:
process_order(body)
ch.basic_ack(delivery_tag=method.delivery_tag)
except RetriableError:
ch.basic_nack(delivery_tag=method.delivery_tag, requeue=True)
except Exception:
ch.basic_nack(delivery_tag=method.delivery_tag, requeue=False)
channel.basic_consume(queue='orders.process', on_message_callback=callback)
channel.start_consuming()Prefetch only has an effect if consumers acknowledge messages manually (auto_ack=False). With auto_ack=True, RabbitMQ considers every message acknowledged the instant it's sent over the wire, so prefetch limiting has nothing to throttle against and messages will still be delivered as fast as the network allows regardless of the prefetch_count you set.
Prefetch, Memory, and Crash Blast Radius
Every unacknowledged message counts against the consumer's in-flight window and also stays resident in the queue's unacked index on the broker side, so a very high prefetch on many consumers can meaningfully inflate broker memory usage during a processing backlog. More importantly, if a consumer crashes or its connection drops, every message it had prefetched but not yet acknowledged is requeued and redelivered (with the redelivered flag set) to another consumer — a prefetch of 1000 on a consumer that dies mid-batch means 1000 messages suddenly need reprocessing elsewhere, potentially all at once. Tuning prefetch is therefore as much about limiting blast radius on failure as it is about throughput.
Cricket analogy: It is like a team fielding an entire outfield of catches to one fielder positioned deep at long-on — if that fielder twists an ankle mid-over, every catch that would have gone to them is suddenly unfielded and the captain scrambles to cover, exactly like a crashed high-prefetch consumer dumping its backlog.
A good starting heuristic: for long or variable-duration tasks, start with prefetch_count=1 and only raise it if profiling shows idle network round-trip time between broker and consumer. For short, uniform tasks, start around 20-50 and tune based on observed consumer memory and redelivery-on-crash blast radius rather than throughput alone.
- Default prefetch is unlimited, which can let one slow consumer hoard messages while idle consumers starve.
- basic.qos(prefetch_count=N) caps unacknowledged messages per consumer, applying per-consumer since RabbitMQ 3.3.
- Prefetch=1 maximizes fairness for long/variable tasks; higher values improve throughput for short, uniform tasks.
- Prefetch only throttles anything when consumers use manual acknowledgment (auto_ack=False).
- Unacknowledged prefetched messages occupy broker memory in the queue's unacked index.
- A crashed consumer requeues and redelivers all of its prefetched-but-unacked messages at once.
- Prefetch tuning balances throughput against the blast radius of a consumer crash.
Practice what you learned
1. What is RabbitMQ's default prefetch behavior if basic.qos is never called?
2. Under what condition does setting prefetch_count have no throttling effect at all?
3. What happens to a consumer's prefetched-but-unacknowledged messages if that consumer's connection drops?
4. Which scenario is the best fit for a very low prefetch value like 1?
Was this page helpful?
You May Also Like
Message Durability and Persistence
Learn how RabbitMQ keeps queues and messages alive across broker restarts using durable queues, persistent delivery mode, and the trade-offs involved in guaranteeing data survives a crash.
Publisher Confirms
Learn how RabbitMQ's publisher confirm mechanism lets a producer know for certain that a message was safely received and persisted by the broker, closing the gap that durability alone leaves open.
Dead Letter Exchanges
Learn how RabbitMQ reroutes rejected, expired, or overflowed messages to a dead letter exchange so failures become observable and recoverable instead of silently vanishing.