`pip install llama-cpp-python`でハマる人へ。AIも間違えたインストールの罠と正解

Last updated at 2025-09-20Posted at 2025-09-20

llama-cpp-pythonのインストールについて

ローカル環境でLLMを動かす第一歩として人気のllama-cpp-python。しかし、このライブラリのインストールには、多くの人がハマる「罠」が仕掛けられています。

pipの常識が通用せず、AIアシスタント（何を隠そう、本記事の共同執筆者であるGoogleのGemini）ですら、最初は間違えるほどでした。この記事では、そのハマりポイントと、コピペで解決できる正しいインストール方法を解説します。

時間がない人向けに、まず結論から。
Windows/macOS/Linux環境で、手軽にCPU版をインストールしたい場合、以下のコマンドを実行してください。

pip install llama-cpp-python --prefer-binary --no-cache-dir --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cpu

多くの場合、これでビルドエラーを回避して、すんなりインストールが完了するはずです。

注意
2025-09-20時点では、この方法だとllama-cpp-pythonのバージョンは少し前の0.3.2です。
Qwen2.5などは使えますが、Qwen3やGemma3は使えませんでした。
なお、ビルドした場合は最新の0.3.16になりQwen3やGemma3も使えます。

pipの常識では、pip install <ライブラリ名> を実行すると、環境に合ったホイール（.whl） という「完成品」が自動でインストールされるはずです。

しかし、このライブラリで同じことをすると、ソースコードからのビルドが始まり、C++のビルド環境がないPCではエラーで失敗します。

Building wheels for collected packages: llama_cpp_python
ERROR: Failed building wheel for llama_cpp_python

なぜこうなるのか？
恐らくですが、開発者は 「各環境でビルドすること」を推奨しているため、公式PyPIにはあえて汎用ホイールを登録していない可能性があります。

llama-cpp-pythonは、PCのハードウェア性能を極限まで引き出すことを重視しています。CPUの特殊な命令（AVX2など）や、GPU（CUDA）の有無など、ユーザーの環境は千差万別です。

そのため、「各ユーザーのPCでビルドして、そのマシンに最適化された実行ファイルを作る」のが、最も性能を引き出せるインストール方法（公式ルート）としているようです。

しかし、これにはC++ビルド環境（WindowsならVisual Studioなど）の準備が必要で、初心者にはハードルが高いのも事実です。

そこで開発者は、ビルドが難しい人や、手軽にCPU版を試したい人向けに、別の場所に汎用的なwhlファイルを用意してくれています。

これが、冒頭で紹介した --extra-index-url 付きのコマンドの正体です。このコマンドは、pipに対して「公式倉庫だけでなく、開発者が用意したこの予備倉庫も見に行って、そこにある完成品をインストールしてね」と指示しているのです。

実は、llama-cpp-pythonの公式サイトに書いているんですけどね、このことは。

実はこの記事、最初はGeminiくんにインストール方法を聞いてみたところ、見事にビルドエラーに誘導されました😅ｗ
その経験をもとに、インストール方法を整理したのが本記事です。

インストール方法は、「忙しい人のために：まずこのコマンドを試せ！」のセクションをご覧ください。

llama-cpp-pythonのインストールでハマるポイントは、ライブラリの特殊な配布戦略にありました。

ローカルLLMの世界へようこそ！この記事が、あなたの第一歩をスムーズにする助けとなれば幸いです。
最後までお読みいただきありがとうございました。
この記事が少しでもお役に立ちましたら、今後の励みになりますので『いいね』をいただけると嬉しいです！