Gemini API SDK バージョン不一致・インストールエラーの原因と解決方法

Gemini API SDK を使い始めようとしたとき、インストールがうまくいかなかったり、コードを実行すると AttributeError や ModuleNotFoundError、ImportError といったエラーが出たりした経験はありませんか？

これらのほとんどは、SDK のバージョン不一致や環境設定の問題が原因です。ここではPython・Node.js それぞれの SDK でよく発生するインストールエラーと解決手順を、ステップバイステップで丁寧に説明します。

よく発生する症状

まず、どのようなエラーが「SDK バージョン不一致・インストール問題」に起因するのかを確認しましょう。

Python SDK（google-generativeai / google-genai）

ModuleNotFoundError: No module named 'google.generativeai'
ImportError: cannot import name 'GenerativeModel' from 'google.generativeai'
AttributeError: module 'google.generativeai' has no attribute 'GenerativeModel'
TypeError: configure() got an unexpected keyword argument 'api_key'

Node.js SDK（@google/generative-ai / @google/genai）

Error: Cannot find module '@google/generative-ai'
TypeError: GoogleGenerativeAI is not a constructor
SyntaxError: The requested module '@google/generative-ai' does not provide an export named 'GoogleGenerativeAI'

これらのエラーに心当たりがあれば、以下の原因分析と解決手順を参考にしてください。

原因の分析

パターン 1：旧パッケージ名を使用している

2024年後半から Gemini API の SDK パッケージ名が変更されましました。

• Python: google-generativeai → google-genai
• Node.js: @google/generative-ai → @google/genai

古いチュートリアルや記事を参考にコードを書いていると、旧パッケージ名のまま使い続けてしまいます。旧パッケージと新パッケージではクラス名・メソッド名が異なるため、混在すると必ず ImportError や AttributeError が発生します。

パターン 2：複数の仮想環境・Python バージョンが混在している

pip install したのに ModuleNotFoundError が出る場合、インストール先の Python 環境とコードを実行する Python 環境が異なっている可能性があります。特に python と python3、あるいは複数の venv が共存している環境で起きがちです。

パターン 3：古いバージョンがキャッシュに残っている

pip や npm のキャッシュに古いバージョンが残っていると、インストールコマンドを実行しても最新版に更新されないことがあります。

パターン 4：Node.js / Python のバージョンが古い

最新の Gemini API SDK は、特定バージョン以上の実行環境を必要とします。

• Python: 3.9 以上（推奨 3.10+）
• Node.js: 18 以上（推奨 20 LTS）

これより古い環境ではインストールに失敗したり、実行時エラーが発生したりします。

パターン 5：依存関係の競合（Dependency Conflict）

他のパッケージとの依存関係が競合し、インストールが中断されるケースもあります。特に protobuf や grpcio などのバイナリパッケージとの競合が多く見られます。

解決手順（Python 編）

Step 1：現在インストールされているパッケージを確認する

# インストール済みの Gemini 関連パッケージをすべて確認
pip list | grep -i google

出力例:

google-generativeai     0.8.3
google-genai            1.3.0

もし両方がインストールされている場合は、必ず片方（原則として古い google-generativeai）を削除してください。

Step 2：旧パッケージを削除し、新パッケージをクリーンインストールする

# 旧パッケージを削除
pip uninstall google-generativeai -y
 
# キャッシュをクリアしてから新パッケージをインストール
pip install --no-cache-dir google-genai
 
# バージョンを確認
pip show google-genai

期待する出力（バージョンは変わる場合があります）:

Name: google-genai
Version: 1.10.0

Step 3：正しいパッケージ名でインポートする

新パッケージ（google-genai）を使う場合のインポートは以下の通りです。

# ✅ 新しい SDK の正しいインポート
from google import genai
 
client = genai.Client(api_key="YOUR_GEMINI_API_KEY")
response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Hello, Gemini!"
)
print(response.text)
# → Hello! How can I help you today?

旧パッケージ（google-generativeai）のコードと混在させると必ずエラーになるため、import 文をコード全体で統一してください。

Step 4：仮想環境を使って環境を分離する（推奨）

# 新しい仮想環境を作成
python3 -m venv gemini_env
 
# 仮想環境を有効化（Mac/Linux）
source gemini_env/bin/activate
 
# 仮想環境を有効化（Windows）
gemini_env\Scripts\activate
 
# 仮想環境内にインストール
pip install google-genai
 
# 仮想環境内のパッケージを確認
pip list | grep google

仮想環境を使うことで、他のプロジェクトとの依存関係の競合を完全に回避できます。

Step 5：Python のバージョンを確認する

python3 --version
# Python 3.12.3
 
# 3.9 未満の場合はアップグレードを検討してください

解決手順（Node.js 編）

Step 1：インストール済みのパッケージを確認する

# package.json の依存関係を確認
cat package.json | grep google
 
# インストール済みパッケージのバージョンを確認
npm list @google/genai 2>/dev/null
npm list @google/generative-ai 2>/dev/null

Step 2：旧パッケージを削除して新パッケージをインストールする

# 旧パッケージを削除
npm uninstall @google/generative-ai
 
# キャッシュをクリアしてから新パッケージをインストール
npm cache clean --force
npm install @google/genai
 
# バージョン確認
npm list @google/genai

Step 3：正しいインポート構文を使う

// ✅ 新しい SDK（@google/genai）の正しいインポート（ES Modules）
import { GoogleGenAI } from "@google/genai";
 
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
 
async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: "Hello, Gemini!",
  });
  console.log(response.text);
  // → Hello! How can I help you today?
}
 
main();

Step 4：Node.js のバージョンを確認する

node --version
# v20.11.0
 
# 18 未満の場合は nvm でアップグレードしてください
nvm install 20
nvm use 20

解決できたかの確認方法

修正後、以下のシンプルなコードを実行して動作確認してください。

Python:

from google import genai
 
client = genai.Client(api_key="YOUR_GEMINI_API_KEY")
response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Say 'SDK is working' in one sentence."
)
print(response.text)
# → SDK is working correctly!

Node.js:

import { GoogleGenAI } from "@google/genai";
 
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const res = await ai.models.generateContent({
  model: "gemini-2.5-flash",
  contents: "Say 'SDK is working' in one sentence.",
});
console.log(res.text);
// → SDK is working correctly!

エラーなくレスポンスが返れば、SDK は正常に動作しています。

予防策：再発防止のベストプラクティス

1. 公式ドキュメントを参照してバージョンを固定する

プロジェクトには常に公式ドキュメントの推奨バージョンを使い、requirements.txt（Python）または package.json（Node.js）にバージョンを明記しましょう。

# requirements.txt の例
google-genai==1.10.0

2. 定期的にアップデートをチェックする

# Python: 最新バージョンを確認
pip index versions google-genai
 
# Node.js: 最新バージョンを確認
npm view @google/genai version

3. CI/CD パイプラインに pip check を組み込む

# 依存関係の競合を検出
pip check
# No broken requirements found.

4. SDK のバージョン移行ガイドを確認する

公式のマイグレーションガイドでは、旧 SDK から新 SDK への変更点が一覧にまとめられています。大きなバージョンアップ時は必ず確認してください。

全体を振り返って

Gemini API SDK のインストール・バージョン問題は、原因さえ特定できれば比較的シンプルに解決できます。

• 旧パッケージ（google-generativeai / @google/generative-ai）は削除し、新パッケージ（google-genai / @google/genai）に統一する
• 仮想環境を活用して依存関係の競合を防ぐ
• Python 3.9+ / Node.js 18+ の実行環境を確認する
• pip check や npm ls で依存関係の整合性を定期的に検証する

この記事を参考に環境を整えて、Gemini API の開発をスムーズに進めていただければ幸いです。SDK 周りの設定が固まったら、ぜひGemini API の公式 Python クイックスタートも参考にしてみてください。