Skip to content
Tutorials Center
My learning

Topics

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.

Python
import queue

q = queue.Queue(maxsize=10)
q.put("job")
print(q.get())

Try it

Python Three kinds of queue

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.

Python Empty, Full and task_done

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):

Python
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

Python
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

  • PriorityQueue returns the smallest item first. Use tuples such as (priority, counter, payload). If two priorities tie, Python compares the next tuple elements, which fails with TypeError for payloads that cannot be ordered; a running counter as the second element avoids that.
  • empty() and full() are hints. In threaded code another thread may change the queue right after the check. Prefer get(timeout=...) and catch queue.Empty.
  • Forgetting task_done() makes join() wait forever. Call it once for every successful get(), also when processing fails (use try/finally).
  • Stopping workers: put one sentinel value (often None) per worker, or use shutdown() on Python 3.13+.
  • SimpleQueue has only put, get, empty and qsize. It is unbounded, reentrant, and has no task_done() or join().
  • Not for processes. Threads share these queues. Use multiprocessing.Queue between processes and asyncio.Queue between coroutines; the three are different classes with similar APIs.
  • Not iterable. There is no way to peek without removing; q.queue is an undocumented implementation detail.