Get size of priority queue in Python: qsize, empty, full, maxsize (2026)

You need the length of a PriorityQueue to cap work, log progress, or guard UI state. The standard library exposes qsize(), plus empty() and full() for quick boolean checks. This page gives a quick answer, how to build a queue, how size relates to maxsize, why qsize() can be approximate under concurrency, and how that compares to a plain FIFO Queue.

Tested on: Python 3.13.3; kernel 6.14.0-37-generic.

Quick answer: get PriorityQueue size in Python

Call qsize() on the queue object. It returns the current number of items waiting in the queue (not including items being handled by consumers mid-get in a racey sense—see below).

python


from queue import PriorityQueue

pq = PriorityQueue()
pq.put((1, "low"))
pq.put((0, "high"))
print(pq.qsize())

Output

Running it prints 2 before any get().

What is PriorityQueue in Python?

queue.PriorityQueue is a thread-safe min-heap queue: get() removes the smallest item according to normal comparison rules. That heap structure is related to the tree data structures used in many scheduling and search algorithms. Typical patterns store tuples such as (priority_number, payload) so ordering is explicit. It is useful for scheduling, merging sorted streams, and graph algorithms (for example Dijkstra-style relaxations) where the next “best” item should come first—not strict FIFO unless priorities tie.

Import PriorityQueue from queue module

Import the class from the queue standard library (not collections).

python

from queue import PriorityQueue

pq = PriorityQueue()
print(type(pq).__name__)

Output

You should see PriorityQueue.

Create a PriorityQueue in Python

Call PriorityQueue() with no arguments for an unbounded queue (maxsize defaults to 0, meaning infinite). Pass a positive integer to cap how many items put will accept before blocking or raising.

python


from queue import PriorityQueue

bounded = PriorityQueue(maxsize=3)
unbounded = PriorityQueue()
print(bounded.maxsize, unbounded.maxsize)

Output

Output shape: 3 then 0 (zero means no fixed upper bound in the API sense).

Add items to PriorityQueue

Use put(item). Items must be orderable (support comparison). A common pattern is (priority, tie_breaker, data) when two jobs could share the same priority—otherwise ties between equal tuples can break in surprising ways.

python


from queue import PriorityQueue

pq = PriorityQueue()
pq.put((2, "second"))
pq.put((1, "first"))
pq.put((3, "third"))
print("size after put:", pq.qsize())
print("smallest:", pq.get())
print("size after get:", pq.qsize())

Output

The first get() returns (1, "first") because 1 is the smallest priority; qsize() drops from 3 to 2.

Get size of PriorityQueue using qsize()

Queue.qsize() returns an approximate count of queue elements in multi-threaded use; in single-threaded code it matches the intuitive length. There is no separate len(queue) because queues are not list-like sequences.

python


from queue import PriorityQueue

pq = PriorityQueue()
for i in range(5):
    pq.put((i, f"task-{i}"))
print(pq.qsize())

Output

Expect 5.

Check if PriorityQueue is empty or full

qsize() vs empty()

Use empty() when you only need a yes/no answer. It is clearer than qsize() == 0 and matches the rest of the queue API.

python


from queue import PriorityQueue

pq = PriorityQueue()
print(pq.empty(), pq.qsize())
pq.put((0, "x"))
print(pq.empty(), pq.qsize())

Output

First line should show True and 0; after put, False and 1.

qsize() vs full()

full() answers whether the queue has reached maxsize. With the default maxsize=0 (unbounded), full() is documented as never returning True. With a positive maxsize, full() becomes meaningful once enough items are waiting.

python


from queue import PriorityQueue

cap = PriorityQueue(maxsize=2)
cap.put((1, "a"))
cap.put((2, "b"))
print(cap.full(), cap.qsize())

Output

Expect True and 2.

Why qsize() is approximate in Python queues

The official documentation warns that qsize() can be unreliable when another thread may be calling put or get at the same time: the count is not guaranteed to stay stable across those operations without external locking. For strict accounting under concurrency, maintain your own counter with a threading.Lock, or structure work so only one thread observes size. See Python multiprocessing and threading for broader patterns when workers share queues.

PriorityQueue size vs maxsize

Current queue size

qsize() reflects how many items are currently waiting in the queue buffer. It does not include tasks already removed by get() or work not yet put().

Maximum queue size limit

maxsize on the constructor is the upper cap when you choose a bounded queue. put(..., block=True) waits when the queue is full; put(..., block=False) raises queue.Full if there is no room.

python


from queue import PriorityQueue, Full

pq = PriorityQueue(maxsize=1)
pq.put((0, "only"))
try:
    pq.put((1, "overflow"), block=False)
except Full:
    print("queue full")
print(pq.qsize())

Output

You should see queue full (or similar message) and size 1.

Get PriorityQueue size before adding or removing items

qsize() is cheap to call, but the meaningful pattern is: snapshot size, then mutate, then snapshot again—knowing the value can change immediately if other threads participate.

python


from queue import PriorityQueue

pq = PriorityQueue()
print("start", pq.qsize())
pq.put((2, "b"))
print("after put", pq.qsize())
item = pq.get()
print("got", item, "now", pq.qsize())

Output

PriorityQueue example with size tracking

This script simulates a worker draining tasks while printing the remaining backlog.

python


from queue import PriorityQueue

pq = PriorityQueue()
for name, pri in (("log", 2), ("email", 1), ("backup", 3)):
    pq.put((pri, name))

while not pq.empty():
    print("backlog", pq.qsize())
    pri, job = pq.get()
    print("  doing", job, "priority", pri)
print("done, size", pq.qsize())

Output

PriorityQueue vs Queue size in Python

queue.Queue (FIFO) and PriorityQueue share the same size API: qsize(), empty(), full(), put, get. The difference is ordering: Queue returns the oldest insertion; PriorityQueue returns the smallest item by comparison. Size semantics and the “qsize() is approximate” note apply to both. If you implement a custom heap instead of the stdlib queue, binary search trees in Python cover another ordered-structure approach used in search problems.

python


from queue import PriorityQueue, Queue

pq = PriorityQueue()
q = Queue()
pq.put(1)
q.put(1)
print(pq.qsize(), q.qsize())

Output

Both report 1 for a single pending item.

Best practices when checking queue size

Prefer empty() / full() for control flow when that is all you need.
Treat qsize() as a hint under threads; use locks or application-level counters for hard limits.
For equal priorities, include a monotonic tie-breaker in the tuple so items remain totally orderable.
For unbounded queues, do not rely on full(); it will not signal saturation.
When priorities are numeric “lower is more urgent,” document that contract next to put calls so readers match the min-heap behavior.

Summary

Use PriorityQueue.qsize() for the current backlog length, empty() and full() for boolean state, and remember qsize() may be approximate with concurrent producers and consumers. maxsize controls whether full() can ever be true and how put behaves when capped. Queue and PriorityQueue share the same sizing API; only retrieval order differs. Official reference: queue module.

Frequently Asked Questions

1. How do I get the number of items in a PriorityQueue in Python?

Call qsize() on the queue instance; it returns an integer count of items currently stored. Prefer empty() when you only need a boolean, and read the docs if multiple threads race on put and get because qsize() can be approximate.

2. Is Python PriorityQueue a min-heap or a max-heap?

queue.PriorityQueue is a min-heap: the smallest item (by normal comparison rules) is returned first from get(). For max-heap behavior, store negated priorities or use a wrapper type with reversed comparison.

3. When does full() return True on a PriorityQueue?

full() is only useful when you construct the queue with maxsize greater than zero; with the default infinite queue (maxsize 0), full() is documented as never returning True.