🐕

Python仮想環境で「ModuleNotFoundError」が発生する原因とOS別対応策

に公開
Python
error
venv
pip
tech

はじめに

本稿は、Pythonの仮想環境でパッケージをインストールしたにもかかわらず ModuleNotFoundError が発生する問題について、その原因と解決策をOS別に記録するものである。

対象環境

この問題は、以下の環境で確認された。OSごとに手順が異なるため、それぞれの環境を明記する。

  • macOS
    • OS: macOS Sequoia 15.6
    • シェル: Zsh
    • Python: 3.11.8 (pyenv 2.4.0経由)
  • Windows
    • OS: Windows 11 Pro 23H2
    • シェル: PowerShell 7.4.2
    • Python: 3.10.2 (python.org公式インストーラ)
  • Linux
    • OS: Ubuntu 22.04.4 LTS
    • シェル: Bash 5.1.16
    • Python: 3.10.12 (apt)
  • 共通ツール
    • エディタ: Visual Studio Code 1.90.0

問題の概要

プロジェクト用にvenvで仮想環境を構築し、pip installコマンドでrequestsなどのライブラリをインストールした。インストールは成功したが、Pythonスクリプトを実行すると以下のエラーが発生した。

Traceback (most recent call last):
  File "main.py", line 1, in <module>
    import requests
ModuleNotFoundError: No module named 'requests'

原因

このエラーの根本的な原因は、Pythonスクリプトを実行しているPythonインタプリタが、パッケージをインストールした仮想環境内のインタプリタと一致していないことにある。

考えられる具体的な要因は以下の通りである。

  1. 仮想環境が有効化されていない: ターミナルセッションで仮想環境を有効化（activate）し忘れている。そのため、システムのグローバルなPythonインタプリタが使用され、仮想環境にインストールされたパッケージをインポートできない。
  2. IDE/エディタのインタプリタ設定が不適切: Visual Studio CodeなどのIDEが、仮想環境外のPythonインタプリタを認識してスクリプトを実行している。
  3. 複数のPythonバージョンが混在: pythonコマンドとpython3コマンドが異なるインタプリタを指しており、意図しない方が実行されている。

解決策

OSごとに、仮想環境の正しい構築手順と、エラーを解消するための確認方法を記述する。ここでは、標準ライブラリであるvenvの使用を前提とする。

1. 仮想環境の作成と有効化

プロジェクトディレクトリ内で、以下の手順に従い仮想環境を正しくセットアップする。

macOS / Linux (Zsh, Bash)

  1. 仮想環境の作成
    プロジェクトルートで以下のコマンドを実行する。.venvという名前のディレクトリが作成される。

    python3 -m venv .venv

  2. 仮想環境の有効化
    activateスクリプトを実行して仮想環境を有効化する。

    source .venv/bin/activate

    成功すると、シェルのプロンプトの先頭に(.venv)と表示される。

  3. インタプリタとpipのパス確認
    whichコマンドで、現在アクティブなpythonとpipが仮想環境内のものを指しているか確認する。

    which python
# 出力例: /path/to/your/project/.venv/bin/python

which pip
# 出力例: /path/to/your/project/.venv/bin/pip

  4. パッケージのインストールと実行
    この状態でパッケージをインストールし、スクリプトを実行する。

    pip install requests
python your_script.py

  5. 仮想環境の無効化
    作業が終了したら、deactivateコマンドで仮想環境を抜ける。

    deactivate

Windows (PowerShell)

  1. 仮想環境の作成
    macOS/Linuxと同様に、プロジェクトルートでコマンドを実行する。

    python -m venv .venv

  2. 実行ポリシーの確認（初回のみ）
    PowerShellはデフォルトでスクリプトの実行が制限されている場合がある。以下のコマンドで現在のポリシーを確認する。

    Get-ExecutionPolicy

    Restrictedと表示された場合、現在のセッションでのみスクリプト実行を許可するためにポリシーを変更する。

    Set-ExecutionPolicy RemoteSigned -Scope Process

  3. 仮想環境の有効化
    Activate.ps1スクリプトを実行して有効化する。

    .venv\Scripts\Activate.ps1

    プロンプトの先頭に(.venv)が表示されることを確認する。

  4. インタプリタとpipのパス確認
    Get-Commandコマンドレットでパスを確認する。

    Get-Command python
# 出力例: ...\your\project\.venv\Scripts\python.exe

Get-Command pip
# 出力例: ...\your\project\.venv\Scripts\pip.exe

  5. パッケージのインストールと実行

    pip install requests
python your_script.py

  6. 仮想環境の無効化

    deactivate

    なお、コマンドプロンプト（cmd.exe）を使用する場合は、有効化コマンドが異なる点に注意する。

    .venv\Scripts\activate.bat

2. IDE/エディタのPythonインタプリタ設定 (VS Code)

VS Codeで開発する場合、ターミナルとは別にエディタ自体が使用するPythonインタプリタを選択する必要がある。

  1. コマンドパレットを開く（macOS: Cmd+Shift+P, Windows/Linux: Ctrl+Shift+P）。
  2. Python: Select Interpreter と入力し、実行する。
  3. インタプリタのリストが表示される。プロジェクト内の仮想環境（例: ./.venv/bin/python）を選択する。
  4. VS Codeのウィンドウ下部にあるステータスバーに、選択した仮想環境のPythonバージョンが表示されることを確認する。

これにより、VS Codeのデバッガやリンター、実行ボタン (▶) が仮想環境のインタプリタを使用するようになる。

3. python -m pipによる確実なパッケージインストール

仮想環境を有効化していても、PATH環境変数の設定によってはシステムのpipが呼び出されてしまうことがある。これを避けるため、python -m pipという形式でコマンドを実行する方法が推奨される。

# 仮想環境が有効化された状態で実行
python -m pip install requests

このコマンドは、現在アクティブなpythonインタプリタに紐付いたpipモジュールを直接実行するため、意図しないpipが使われるリスクを排除できる。

まとめ

ModuleNotFoundErrorは、Pythonの実行環境とパッケージのインストール先環境の不一致が原因で発生する典型的なエラーである。

問題解決の要点は以下の通り。

  • プロジェクトごとに必ずvenvで仮想環境を作成する。
  • 作業を開始する前に、ターミナルで仮想環境をactivateする。
  • 使用しているIDEやエディタ（VS Codeなど）で、正しいPythonインタプリタ（仮想環境内のもの）が選択されていることを確認する。
  • pip installの代わりにpython -m pip installを使用すると、パッケージのインストール先を間違えるリスクを低減できる。

これらの手順を遵守することで、環境に起因するモジュールのインポートエラーを未然に防ぐことができる。

参照

Discussion