インストールしたのに別の実行画面ではimportできないときは、実行側のPythonと、pipを動かしたPythonを対応させる。確認の出発点は、失敗するプログラム自身が返すsys.executableである。ターミナルでpythonの版だけを見ても、同じ版のPythonが複数ある場合には区別できない。ここでは場所を比較し、同じ実行ファイルでpipを呼ぶところまで整理する。
失敗する場所で情報を出す
下のdiagnose.pyを、エディターの実行ボタンやノートブックなど、実際に失敗する環境で実行する。targetには調べたいimport名を指定する。練習例のtip_demoはローカルに作ったパッケージで、一般公開された配布物をインストールする指示ではない。
executableは起動中のPythonのパス、prefixは現在の環境の基準ディレクトリ、base_prefixは元のPythonの基準ディレクトリである。通常のvenvならprefixとbase_prefixが異なる。VIRTUAL_ENVという環境変数だけでは、現在のPythonを確定できない。
diagnose.py
import importlib.util
import json
import subprocess
import sys
target = "tip_demo"
if not sys.executable:
raise RuntimeError("Python executable could not be identified")
result = subprocess.run(
[sys.executable, "-m", "pip", "--version"],
capture_output=True, text=True, check=False,
)
spec = importlib.util.find_spec(target)
print(json.dumps({
"executable": sys.executable,
"prefix": sys.prefix,
"base_prefix": sys.base_prefix,
"in_venv": sys.prefix != sys.base_prefix,
"pip_returncode": result.returncode,
"pip": result.stdout.strip(),
"pip_error": result.stderr.strip(),
"module_origin": None if spec is None else spec.origin,
}, indent=2))
pipはsys.executableを先頭にした引数リストから呼び出している。これならPATH上に偶然見つかった別のpipを使うことを避けられる。pip自体が入っていなければ、終了コードとstderrも確認する。sys.executableが取得できない特殊な実行環境もあるため、空の場合は明示的に停止させている。
二つの環境で違いを確かめる
動作確認では、一時ディレクトリに独立したvenv A・Bを作り、練習用tip-demoをAだけへインストールした。同じdiagnose.pyをそれぞれのPythonで実行すると、次のように違いが出る。ここでは実機ごとに変わるパスを掲載せず、比較結果を表示している。
実行結果
Environment A: in_venv=True, module_found=True
Environment B: in_venv=True, module_found=False
Different executables: True
Pythonのバージョンが同じでも、Aへ入れたパッケージはBから見えない。診断画面ではexecutableの先頭部分、pipの表示する配置先、module_originの三つを照合する。pipの版番号だけが一致していることを、同じ環境だと判断する根拠にしないようにしたい。
実行ファイルを指定して修正する
使う環境を決めたら、その環境のPythonから-m pipを実行する。次のコマンドはOSごとの書式例であり、パッケージ名は公式文書で確認した配布名へ置き換える。手元のvenvへパッケージを追加する操作なので、先に作業対象を確かめる。
コマンド例：Linux/macOSとWindows PowerShell（Windows/macOS未実行）
# Linux/macOS：.venvを使う場合の書式
.venv/bin/python -m pip --version
.venv/bin/python -m pip show DISTRIBUTION_NAME
.venv/bin/python -m pip install DISTRIBUTION_NAME
# Windows PowerShell：.venvを使う場合の書式
& ".\.venv\Scripts\python.exe" -m pip --version
& ".\.venv\Scripts\python.exe" -m pip show DISTRIBUTION_NAME
& ".\.venv\Scripts\python.exe" -m pip install DISTRIBUTION_NAME
WindowsではScripts、Linux/macOSではbinという配置が一般的である。パスに空白があれば適切に引用する。PowerShellでは引用した実行ファイルを呼ぶときに&を使う。activateはPATHを便利に切り替える仕組みであり、実行ファイルを明示して呼ぶ場合は必須ではない。
エディターとノートブックも合わせる
ターミナル側を直しても、エディターのPython選択やノートブックのカーネルは別に保存されていることがある。実行したいvenvのPythonを選び直してから、もう一度同じ診断を出す。カーネルを切り替えたつもりでも、sys.executableが期待した場所でなければ調査を続ける。
設定変更後はPythonプロセスを新しくし、短いimportと必要な計算を試す。パッケージの配置が確認できるだけでは、内部の依存関係や拡張モジュールまで正常とは限らない。場所がそろっているのに失敗する場合は、症状別のトラブルシューティングへ戻るとよい。
診断結果を共有するときの注意
出力にはユーザー名、ホームディレクトリ、プロジェクト名などが含まれることがある。相談先へ渡すときは、個人情報に当たる部分だけを置換し、AとBの違いや末尾のsite-packagesといった位置関係は残す。全文を無差別に公開する必要はない。
また、PYTHONPATHやユーザー用site-packagesの設定によって検索経路が追加されている場合もある。executableとpipだけで説明できないときはsys.pathも確認するが、その場しのぎでパスを追加し続けるのは避けたい。実行する環境を一つに決め、その環境へ必要なものを入れる方法が再現しやすい。
動作確認と参考資料
掲載例はLinux・CPython 3.12.14で動作確認した。OS固有のコマンドや環境ごとに変わるパスは、本文中の条件を確認して使ってほしい。