Python Reference ยท Standard Library: Concurrency, Network and Tools
The queue module
Reference for Python's queue module: Queue, LifoQueue, PriorityQueue, SimpleQueue, put, get, task_done, join, Empty and Full, with runnable examples.
The queue module provides queues that are safe to share between threads. Every operation takes its own lock, so a producer thread can call put() while a consumer thread calls get() without any extra synchronization from you.
There are four classes: Queue (first in, first out), LifoQueue (last in, first out, like a stack), PriorityQueue (smallest item first) and SimpleQueue (an unbounded FIFO queue without task tracking). Do not confuse it with collections.deque, which is faster but only offers atomic appends and pops, not blocking waits.
import queue q = queue.Queue(maxsize=10) q.put("job") print(q.get())
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.
The examples above run on one thread, because the browser runner does not start real threads. A typical producer and consumer pair looks like this (read-only):
import queue import threading jobs = queue.Queue() def worker(): while True: item = jobs.get() if item is None: # sentinel: time to stop jobs.task_done() break print("processing", item) jobs.task_done() t = threading.Thread(target=worker) t.start() for n in range(5): jobs.put(n) jobs.put(None) jobs.join() t.join()
Syntax
queue.Queue(maxsize=0) queue.LifoQueue(maxsize=0) queue.PriorityQueue(maxsize=0) queue.SimpleQueue()
| Name | Description |
|---|---|
maxsize |
Upper bound on the number of items. 0 or a negative number means unlimited. When the queue is full, put() blocks. |
Methods shared by the classes:
| Method | Description |
|---|---|
put(item, block=True, timeout=None) |
Adds an item. Blocks while the queue is full; with block=False or an expired timeout it raises queue.Full. |
put_nowait(item) |
Same as put(item, block=False). |
get(block=True, timeout=None) |
Removes and returns an item. Blocks while empty; raises queue.Empty if it cannot get one. |
get_nowait() |
Same as get(block=False). |
qsize() |
Approximate number of items. |
empty(), full() |
Approximate checks; the answer may be stale by the time you act on it. |
task_done() |
Tells the queue that one fetched item has been fully processed. |
join() |
Blocks until every item that was put has had task_done() called. |
shutdown(immediate=False) |
Closes the queue (Python 3.13+). Later put() calls raise queue.ShutDown; get() raises it once the queue is drained, or at once with immediate=True. |
Raises: queue.Empty, queue.Full, queue.ShutDown (3.13+), and ValueError if task_done() is called more times than there were items.
Usage notes
PriorityQueuereturns the smallest item first. Use tuples such as(priority, counter, payload). If two priorities tie, Python compares the next tuple elements, which fails withTypeErrorfor payloads that cannot be ordered; a running counter as the second element avoids that.empty()andfull()are hints. In threaded code another thread may change the queue right after the check. Preferget(timeout=...)and catchqueue.Empty.- Forgetting
task_done()makesjoin()wait forever. Call it once for every successfulget(), also when processing fails (usetry/finally). - Stopping workers: put one sentinel value (often
None) per worker, or useshutdown()on Python 3.13+. SimpleQueuehas onlyput,get,emptyandqsize. It is unbounded, reentrant, and has notask_done()orjoin().- Not for processes. Threads share these queues. Use
multiprocessing.Queuebetween processes andasyncio.Queuebetween coroutines; the three are different classes with similar APIs. - Not iterable. There is no way to peek without removing;
q.queueis an undocumented implementation detail.