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以前では番兵を入れる方法を使います。
あわせて読みたい
- Python queue 関数一覧|Queue・LifoQueue・PriorityQueueの使い方
- Python queue クラス一覧|Queue・LifoQueue・PriorityQueue・SimpleQueueの使い方
- Python標準ライブラリのクラスとは?関数・メソッドとの違いも解説
- Python標準ライブラリのメソッドとは?関数との違いや使い方を解説
queue の個別解説
- Python queueとは?スレッド間で安全にデータを渡す方法
- Python Queueのput()とget()とは?データの出し入れと待機の仕組み
- Python Queueのtask_done()とjoin()とは?全タスク完了を待つ方法
queue の関連記事
queueモジュールはメンバー一覧の視点でも整理しています。あわせて読むと、どの名前がどの分類にあたるのかを把握しやすくなります。


