Python @lru_cacheの使い方|maxsize・cache_infoと、効かない原因・メソッドやasyncでの注意点

functools.lru_cacheは、関数に @lru_cache と付けるだけで「同じ引数の結果」を覚えておき、2回目からは計算せずに返すデコレータです。既定では最近使った128件まで保存し(maxsize=128)、maxsize=None にすると上限なしになります。

この記事では、lru_cacheの書き方と引数(maxsize・typed)、効いているかを確かめるcache_info()、そして「キャッシュが効かない」「メソッドに付けたらメモリが減らない」「asyncで使えない」といった落とし穴を、実際に動かした結果つきで説明します。実行環境はPython 3.12.15です(2026年10月18日確認)。

@lru_cacheの基本の書き方

from functools import lru_cache

@lru_cache
def square(n):
    print("計算:", n)
    return n * n

print(square(4))
print(square(4))
print(square.cache_info())

実行結果:

計算: 4
16
16
CacheInfo(hits=1, misses=1, maxsize=128, currsize=1)

2回目は「計算:」が表示されていません。1回目の結果を覚えていて、関数の中身を実行せずに返したためです。

書き方は次の3通りがあり、どれも有効です。かっこを付けない@lru_cacheはPython 3.8から使えます(functools — Python documentation、2026年10月18日確認)。

@lru_cache               # 既定(maxsize=128, typed=False)
@lru_cache()             # 上と同じ
@lru_cache(maxsize=None) # 上限なし

lru_cacheの引数と付いてくる関数

名前 種類 内容
maxsize 引数(既定128) 保存する件数の上限。Noneで上限なし
typed 引数(既定False) Trueなら1と1.0のように型が違う引数を別々に保存する
cache_info() 関数 hits(使われた回数)・misses(計算した回数)・maxsize・currsize(今の件数)を返す
cache_clear() 関数 保存した結果をすべて消す
cache_parameters() 関数(3.9追加) maxsizeとtypedの設定を辞書で返す
__wrapped__ 属性 キャッシュを通さない元の関数
print(square.cache_parameters())

実行結果:

{'maxsize': 128, 'typed': False}

どれくらい速くなるか(再帰のフィボナッチ数列)

from functools import lru_cache
import time

def fib(n):
    return n if n < 2 else fib(n - 1) + fib(n - 2)

@lru_cache(maxsize=None)
def fib_c(n):
    return n if n < 2 else fib_c(n - 1) + fib_c(n - 2)

t = time.perf_counter(); fib(30); t1 = time.perf_counter() - t
t = time.perf_counter(); fib_c(30); t2 = time.perf_counter() - t
print(f"キャッシュなし {t1:.4f}秒 / キャッシュあり {t2:.6f}秒")
print(fib_c.cache_info())

実行結果(Apple M2、2026年10月18日実行):

キャッシュなし 0.0698秒 / キャッシュあり 0.000027秒
CacheInfo(hits=28, misses=31, maxsize=None, currsize=31)

キャッシュなしの再帰は同じfib(n)を何度も計算し直しますが、キャッシュありでは0〜30の31通りを1回ずつ計算するだけ(misses=31)で済んでいます。秒数は環境で変わります。フィボナッチ数列のほかの書き方との比較は「フィボナッチ数列とは?4つの実装を実測比較」で扱っています。

maxsizeの決め方(maxsize=1・Noneの意味)

LRUは「Least Recently Used」の略で、上限を超えると「いちばん長く使われていない結果」から捨てます。

from functools import lru_cache

@lru_cache(maxsize=2)
def f(x):
    print("  計算:", x)
    return x * 2

f(1); f(2); f(1); f(3); f(2)
print(f.cache_info())

実行結果:

  計算: 1
  計算: 2
  計算: 3
  計算: 2
CacheInfo(hits=1, misses=4, maxsize=2, currsize=2)
  1. f(1)・f(2)を計算して保存
  2. f(1)はヒット。1が「最近使った」側に移る
  3. f(3)で上限を超え、いちばん古い2が捨てられる
  4. f(2)は捨てられているので再計算

検索でよく調べられているmaxsize=1は「直前の1件だけ覚える」設定です。同じ引数で続けて呼ばれるときだけ効きます。

@lru_cache(maxsize=1)
def load(name):
    print("  読み込み:", name)
    return name.upper()

load("a"); load("a"); load("b"); load("a")
print(load.cache_info())

実行結果:

  読み込み: a
  読み込み: b
  読み込み: a
CacheInfo(hits=1, misses=3, maxsize=1, currsize=1)

maxsize=Noneは上限なしで、結果を捨てません。上限の管理が要らないぶん速くなり、functools.cacheはlru_cache(maxsize=None)と同じものだと公式ドキュメントに書かれています(使い分けは「Python functools.cache()とは?結果を丸ごとキャッシュする方法」)。ただし引数の種類が多い関数ではメモリが増え続けるので、長く動き続けるプログラムでは上限を決めておくのが安全です。

キャッシュが効かない3つの原因

1. 引数の渡し方が違う

from functools import lru_cache

@lru_cache
def h(a, b=2):
    return a + b

h(1, 2); h(1, b=2); h(a=1, b=2); h(1)
print(h.cache_info())

実行結果:

CacheInfo(hits=0, misses=4, maxsize=128, currsize=4)

どれも同じ計算ですが、4回とも計算されました。キャッシュのキーは「どう渡したか」で作られるため、位置引数とキーワード引数、既定値の省略は別のものとして扱われます。公式ドキュメントにも、f(a=1, b=2)とf(b=2, a=1)は別のキャッシュになりうると書かれています。呼び出し方をそろえてください。

2. 引数にリストや辞書を渡している

@lru_cache
def g(x):
    return x

try:
    g([1, 2])
except TypeError as e:
    print("TypeError:", e)
print(g((1, 2)))

実行結果:

TypeError: unhashable type: 'list'
(1, 2)

結果を辞書に保存する仕組みなので、引数はハッシュ可能(変更できない型)でなければなりません。リストはタプルに、辞書はtuple(d.items())などに変えて渡します。

3. typedの設定

既定のtyped=Falseでは1と1.0は同じ引数として扱われます。typed=Trueにすると別々に保存されるので、ヒットしにくくなります。

@lru_cache(typed=True)
def ty(x):
    print("  計算:", repr(x))
    return x

ty(1); ty(1.0)
print(ty.cache_info())

実行結果:

  計算: 1
  計算: 1.0
CacheInfo(hits=0, misses=2, maxsize=128, currsize=2)

付けてはいけない関数

公式ドキュメントは、副作用のある関数、呼ぶたびに別のオブジェクトを返すべき関数(ジェネレータやasync関数)、time()やrandom()のように結果が変わる関数にはキャッシュは意味がない、としています。

戻り値のリストを書き換えると、キャッシュも変わる

@lru_cache
def items():
    return [1, 2, 3]

x = items()
x.append(99)
print(items())

実行結果:

[1, 2, 3, 99]

キャッシュは戻り値そのものを保存しているので、受け取った側でリストを変更すると、次に返る値も変わってしまいます。リストを返す関数にキャッシュを付けるなら、タプルで返すか、受け取った側でコピーしてから変更してください。

async関数に付けると2回目でエラー

import asyncio
from functools import lru_cache

@lru_cache
async def fetch(n):
    return n * 10

async def main():
    print(await fetch(1))
    try:
        print(await fetch(1))
    except RuntimeError as e:
        print("RuntimeError:", e)

asyncio.run(main())

実行結果:

10
RuntimeError: cannot reuse already awaited coroutine

キャッシュされるのは結果ではなく「コルーチン」というオブジェクトで、これは一度しかawaitできないためです。非同期の結果をキャッシュしたいときは、結果を自分で辞書に保存するなど別の方法を使います。

クラスのメソッドに付けるときの注意

メソッドに@lru_cacheを付けると、self(インスタンス)も引数としてキャッシュに保存されます。そのため、インスタンスを消してもキャッシュから追い出されるまでメモリに残ります。

from functools import lru_cache
import gc, weakref

class Station:
    def __init__(self, name):
        self.name = name

    @lru_cache(maxsize=32)
    def rainfall(self, date):
        return f"{self.name}:{date}"

s = Station("tokyo")
r = weakref.ref(s)
s.rainfall("10-18")
del s
gc.collect()
print("delのあとも残っている:", r() is not None)

Station.rainfall.cache_clear()
gc.collect()
print("cache_clear後も残っている:", r() is not None)

実行結果:

delのあとも残っている: True
cache_clear後も残っている: False

公式のFAQ(How do I cache method calls?、2026年10月18日確認)でも、lru_cacheはインスタンスを生かし続ける、引数のないメソッドならfunctools.cached_propertyを使えばインスタンスと一緒に結果も消える、と説明されています。インスタンスを大量に作るクラスでは、cached_propertyを検討してください。

スレッドから使う場合・有効期限

公式ドキュメントによると、lru_cacheはスレッドセーフで、複数のスレッドから同時に呼んでも内部のデータは壊れません。ただし、最初の呼び出しが終わってキャッシュされる前に別のスレッドが同じ引数で呼ぶと、関数が2回以上実行されることがあります。

lru_cacheには「何秒たったら消す」という有効期限の機能はありません。外部のデータを読み込む関数で古い結果を使い続けたくないときは、データを更新したタイミングでcache_clear()を呼びます。

よくある質問

Q. lru_cacheのmaxsizeの既定値はいくつですか?

128です。@lru_cache とかっこなしで書いた場合も maxsize=128 になります。上限なしにするには maxsize=None を指定します。

Q. maxsize=Noneとfunctools.cacheの違いは?

公式ドキュメントでは、functools.cache は lru_cache(maxsize=None) と同じものを返すとされています。Python 3.9以降なら、上限が要らないときは @cache と書くほうが意図が伝わります。

Q. キャッシュが効いているか確かめるには?

関数名.cache_info() を表示します。hits が増えていればキャッシュが使われています。hits が0のままなら、引数の渡し方が毎回違う、引数の種類が多すぎるなどの原因を疑います。

Q. lru_cacheでTypeError: unhashable type: ‘list’が出ます。

引数にリストや辞書などハッシュできない値を渡しているためです。リストはタプルに変換してから渡してください。

Q. クラスのメソッドにlru_cacheを付けてもいいですか?

付けられますが、self もキャッシュに保存されるため、インスタンスがキャッシュから追い出されるまでメモリに残ります。引数のないメソッドなら functools.cached_property のほうが向いています。

まとめ

  • @lru_cacheは同じ引数の結果を覚えて再利用する。既定はmaxsize=128
  • 効いているかはcache_info()のhitsで確かめる
  • 引数の渡し方が違うと別のキャッシュになる。リストは渡せない
  • 戻り値を書き換えるとキャッシュも変わる。async関数には使えない
  • メソッドに付けるとインスタンスが残る。引数なしならcached_property
  • 有効期限はない。データを更新したらcache_clear()

デコレータの仕組みそのものは「Pythonのデコレータとは?仕組み・書き方・引数付き・functools.wrapsを実行結果で解説」、キャッシュの考え方全般は「キャッシュ戦略とは?」で説明しています。

速さやメモリの問題は、実際に計測しながら学ぶと身につきます。テックジムは永田町の東京本校などに通って学ぶ対面型のプログラミングスクールで、自分のペースで課題を進め、分からないところはトレーナーに質問できます。まずは無料Python講座(ゼロからはじめるPython入門講座)から試すこともできます。

あわせて読みたい

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

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

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

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

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

参加者の声

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

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

参加費は無料です