Python queueのメソッド一覧|get_nowait()とget()の違い・put_nowait・task_done・join・shutdown

Pythonのqueue.Queueのメソッドは、出し入れのput()・get()、待たずに出し入れするput_nowait()・get_nowait()、完了を管理するtask_done()・join()、状態を見るqsize()・empty()・full()、そしてPython 3.13で加わったshutdown()です。get_nowait()はget(block=False)と同じで、キューが空ならすぐにqueue.Emptyを出します。

この記事では、公式ドキュメント(queue — 同期キュークラス、2026年10月18日確認)をもとに、メソッドごとの「待つか・どの例外を出すか」を一覧にし、get_nowait()とget()の違いを中心に、Python 3.12で実行した結果つきで解説します。キューのクラスの選び方は「Python queue クラス一覧」、モジュール全体の入門は「Python queueとは?スレッド間で安全にデータを渡す方法」で扱っています。

queueのメソッド一覧(待つか・出す例外)

Queue・LifoQueue・PriorityQueueは同じメソッドを持ちます。実際にdir()で確かめると、公開されている名前は次のとおりです(Python 3.12)。

import queue

q = queue.Queue()
print([m for m in dir(q) if not m.startswith("_")])

実行結果:

['all_tasks_done', 'empty', 'full', 'get', 'get_nowait', 'join', 'maxsize', 'mutex', 'not_empty', 'not_full', 'put', 'put_nowait', 'qsize', 'queue', 'task_done', 'unfinished_tasks']

mutexやnot_emptyなどは内部で使うロックや条件変数なので、使うのは次の表のメソッドだけです。

メソッド 働き 待つか 出す例外
put(item, block=True, timeout=None) 入れる 満杯なら空くまで待つ timeout切れでFull
put_nowait(item) 入れる(put(item, block=False)と同じ) 待たない 満杯ならFull
get(block=True, timeout=None) 取り出す 空なら入るまで待つ timeout切れでEmpty
get_nowait() 取り出す(get(False)と同じ) 待たない 空ならEmpty
task_done() 取り出した1件の処理が終わったと知らせる ― 呼びすぎるとValueError
join() 全件のtask_done()を待つ 待つ ―
qsize() おおよその件数 ― ―
empty() / full() 空か・満杯か ― ―
shutdown(immediate=False) キューを閉じる(3.13〜) ― 以後のput()などでShutDown

Empty・Full・ShutDownはどれもqueueモジュールの例外なので、except queue.Empty:のように書きます。

get_nowait()の使い方:空ならすぐqueue.Empty

import queue

q = queue.Queue()
q.put("A")
q.put("B")

print(q.get_nowait())
print(q.get_nowait())

try:
    q.get_nowait()
except queue.Empty:
    print("空なので queue.Empty")

実行結果:

A
B
空なので queue.Empty

データがあればget()と同じように取り出し、なければ待たずにqueue.Emptyを出します。get_nowait()は必ずtry〜except queue.Emptyで囲むのが基本の形です。

get_nowait()とget()・get(timeout=)の違い

キューが空のときの動きだけが違います。

書き方 空のときの動き 向いている場面
get() データが入るまでずっと待つ ワーカースレッドが仕事を待ち続ける
get(timeout=1.5) 最大1.5秒待って、来なければEmpty 待ちつつ、定期的に別の確認もしたい
get_nowait()(get(block=False)) 待たずにすぐEmpty GUIやゲームのループで、あれば処理・なければ次へ

公式ドキュメントにあるとおり、block=Falseのときはtimeoutが無視されます。実際に測ってみます。

import queue
import time

q = queue.Queue()

start = time.perf_counter()
try:
    q.get(timeout=1.5)
except queue.Empty:
    print(f"queue.Empty({time.perf_counter() - start:.1f}秒待った)")

start = time.perf_counter()
try:
    q.get(block=False, timeout=5)
except queue.Empty:
    print(f"queue.Empty({time.perf_counter() - start:.1f}秒待った)")

実行結果:

queue.Empty(1.5秒待った)
queue.Empty(0.0秒待った)

引数なしのget()を空のキューで呼ぶと、別のスレッドがput()するまで戻ってきません。プログラムが固まったように見えたら、まずここを疑ってください。

put_nowait()の使い方:満杯ならすぐqueue.Full

maxsizeを指定したキューでは、満杯のときの動きがput()とput_nowait()で変わります。

import queue

q = queue.Queue(maxsize=2)
q.put_nowait("A")
q.put_nowait("B")
print(q.full(), q.qsize())

try:
    q.put_nowait("C")
except queue.Full:
    print("満杯なので queue.Full")

try:
    q.put("C", timeout=0.5)
except queue.Full:
    print("0.5秒待っても空かないので queue.Full")

実行結果:

True 2
満杯なので queue.Full
0.5秒待っても空かないので queue.Full

maxsizeを省略した(0の)キューは上限がないので、put_nowait()がFullを出すことはありません。ログやセンサーの値など「溢れたら捨ててよい」データを、上限つきのキューにput_nowait()で入れ、Fullのときは捨てる、という使い方ができます。

get_nowait()でキューを空にする

たまっているデータをその場で全部取り出したいときは、get_nowait()をEmptyが出るまで繰り返します。

import queue

def drain(q):
    items = []
    while True:
        try:
            items.append(q.get_nowait())
        except queue.Empty:
            return items

q = queue.Queue()
for i in range(5):
    q.put(i)

print(drain(q))
print(q.empty())

実行結果:

[0, 1, 2, 3, 4]
True

while not q.empty(): q.get()と書くこともできますが、複数のスレッドが同じキューから取り出していると、empty()で確認した直後に他のスレッドに取られ、get()で止まることがあります。公式ドキュメントにも「empty()がFalseを返しても、後続のget()がブロックしないことは保証されません」と書かれています。確認してから取るより、取ってみてEmptyを受け止めるほうが安全です。qsize()も同じ理由で「おおよその件数」です。

task_done()とjoin():全件の完了を待つ

import queue
import threading

q = queue.Queue()
results = []

def worker():
    while True:
        item = q.get()
        try:
            results.append(item * 10)
        finally:
            q.task_done()

for _ in range(3):
    threading.Thread(target=worker, daemon=True).start()

for i in range(10):
    q.put(i)

q.join()
print(sorted(results))
print("すべて完了")

実行結果:

[0, 10, 20, 30, 40, 50, 60, 70, 80, 90]
すべて完了

キューの中には「未完了の件数」があり、put()で1増え、task_done()で1減ります。join()はこれが0になるまで待ちます。get()したら必ずtask_done()を呼ぶ決まりで、処理中に例外が出ても呼ばれるようtry〜finallyにしておくと、join()が永久に終わらない事故を防げます。

逆に、put()した件数より多く呼ぶとエラーになります。

import queue

q = queue.Queue()
q.put("A")
q.get()
q.task_done()

try:
    q.task_done()
except ValueError as e:
    print("ValueError:", e)

実行結果:

ValueError: task_done() called too many times

この2つのメソッドの仕組みは「Python Queueのtask_done()とjoin()とは?全タスク完了を待つ方法」で詳しく解説しています。なお、スレッドのThread.join()はスレッドの終了を待つ別のメソッドです。

ワーカーを止める:番兵とshutdown()

Python 3.12以前でワーカーを止めるには、「これが来たら終わり」という目印(番兵、sentinel)を入れる方法が定番です。

import queue
import threading

q = queue.Queue()
STOP = object()

def worker():
    while True:
        item = q.get()
        if item is STOP:
            q.task_done()
            break
        print("処理:", item)
        q.task_done()

t = threading.Thread(target=worker)
t.start()

q.put("A")
q.put("B")
q.put(STOP)

q.join()
t.join()
print("終了しました")

実行結果:

処理: A
処理: B
終了しました

Python 3.13ではQueue.shutdown()と例外queue.ShutDownが追加されました(公式ドキュメント「Added in version 3.13」)。公式の説明によると、動きは次のとおりです。

  • shutdown()(immediate=False)を呼ぶと、以後のput()はShutDownを出す。残っているデータはget()で取り出せ、空になるとget()がShutDownを出す
  • shutdown(immediate=True)は残りのデータを捨てて即座に閉じる。待っているget()もShutDownで戻る
  • immediate=Trueでは処理していないタスクの分も未完了数から引かれるため、join()が仕事をしないまま戻ることがある(公式も注意を促している)

3.13以降ならワーカーをexcept queue.ShutDown: breakで抜けられるため、ワーカーの数だけ番兵を入れる必要がなくなります。動作環境に3.12以前が残るなら番兵の方法を使います。shutdown()を含むメンバーの対応表は「Python queue メンバー一覧」にまとめています。

SimpleQueueで使えるメソッド

import queue

sq = queue.SimpleQueue()
print([m for m in dir(sq) if not m.startswith("_")])

実行結果:

['empty', 'get', 'get_nowait', 'put', 'put_nowait', 'qsize']

SimpleQueueにはtask_done()・join()・full()がありません。上限もないため、公式ドキュメントによるとput()は決して待たず、blockとtimeoutはQueue.put()との互換のためだけにあって無視されます。完了待ちが要らない単純な受け渡しに向いています。

multiprocessing.Queueとasyncio.Queueのget_nowait()

同じ名前のメソッドを持つ別のキューもあります。

キュー 使う場面 get_nowait()の注意
queue.Queue スレッド間 空ならqueue.Empty
multiprocessing.Queue プロセス間 空ならqueue.Empty。空のキューにput()した直後は、データが届くまでのわずかな遅れでEmptyになることがある
asyncio.Queue 非同期処理(コルーチン間) 空ならasyncio.QueueEmpty(queue.Emptyではない)

multiprocessing.Queueの遅れについては、multiprocessingの公式ドキュメントの「パイプとキュー」の節に記載があります(データはpickle化されてバックグラウンドのスレッドで送られるため)。プロセス間でget_nowait()を使うなら、get(timeout=...)で少し待つほうが確実です。asyncio.Queueについては「Python asyncio.Queueの使い方」をご覧ください。

queueメソッドの選び方まとめ

やりたいこと 使うメソッド
データを入れる put()
満杯なら待たずに諦める put_nowait()+except queue.Full
データが来るまで待って取り出す get()
一定時間だけ待つ get(timeout=秒)+except queue.Empty
あれば取り出し、なければすぐ次へ get_nowait()+except queue.Empty
1件の処理完了を知らせる task_done()
全件の完了を待つ join()
キューを閉じてワーカーを止める shutdown()(3.13〜)または番兵
件数の目安を見る qsize()(概算)

よくある質問

Q. Python queueのget_nowait()とget()の違いは何ですか?

キューが空のときの動きが違います。get()はデータが入るまで待ち続け、get_nowait()は待たずにすぐqueue.Emptyを出します。get_nowait()はget(block=False)と同じです。

Q. get_nowait()でqueue.Emptyが出たらどうすればよいですか?

空だったという正常な合図なので、try〜except queue.Emptyで受け止めて、次の処理へ進むか、少し待ってから取り直します。待ちながら取りたいなら、get(timeout=秒)を使うと書き方が簡単です。

Q. put_nowait()はどんなときにqueue.Fullになりますか?

maxsizeを指定したキューが満杯のときです。maxsizeを省略したキューには上限がないので、put_nowait()がqueue.Fullを出すことはありません。

Q. empty()で確認してからget()するのはだめですか?

複数のスレッドが取り出すキューでは、確認した直後に他のスレッドに取られてget()で止まることがあります。公式ドキュメントも保証しないと明記しているので、get_nowait()で取ってみてqueue.Emptyを受け止める書き方が安全です。

Q. Queue.shutdown()はいつから使えますか?

Python 3.13からです。shutdown()を呼ぶと以後のput()がqueue.ShutDownを出し、残りを取り出し終えるとget()もqueue.ShutDownを出すので、ワーカーを止める合図に使えます。3.12以前では番兵を入れる方法を使います。

あわせて読みたい


queue の個別解説


queue の関連記事

queueモジュールはメンバー一覧の視点でも整理しています。あわせて読むと、どの名前がどの分類にあたるのかを把握しやすくなります。

対面・無料|東京・永田町で毎週土曜日13時

この記事のようなコードを、講師に聞きながら動かしてみる

ゼロからはじめるPython入門講座

8年間・累計600回開催/これまで全国で2万人以上が参加

「やはり対面で聞けるのはとても気づきがあり、価値があると思います」

参加者の声

  • 本当に初心者からの講座です。プログラミングに触ったことがなくて大丈夫です
  • 対面だから、その場で聞けます。つまずいた所を持ち帰らずに解決できます
  • 講座は1時間。そのあとも残って学習を続けられ、講師にも質問できます
  • 独学で挫折した方も。糸口が見つかって、講座のあと会員になる方が多くいます

無料で参加する|開催日程を見る

参加費は無料です