Python仮想環境入門：venvの使い方とrequirements.txt

仮想環境が解決してくれる悩み

Pythonをインストールして pip install requests を叩くと、パッケージはシステム全体の1か所にインストールされます。プロジェクトが1つだけなら、これでも困りません。ですが3つ目くらいから、じわじわと問題が出てきます。

• プロジェクトAは django==3.2 が必要で、プロジェクトBは django==5.0 が必要。グローバルには片方のバージョンしか入れられません。
• 新しいライブラリを試したいけれど、他のプロジェクト全部を汚したくない。
• チームメイトがリポジトリをcloneしても、どのパッケージのどのバージョンに依存しているのか分からない。

こんなときに使うのが python 仮想環境 です。仮想環境とは、Pythonインタプリタと専用のライブラリインストール先をまとめて持っている、独立したフォルダのこと。仮想環境を「アクティベート」すると、ターミナルで打つ python や pip は、システム側のPythonではなくそのフォルダの中を指すようになります。そこにインストールしたパッケージは、その中だけに留まります。

venv で仮想環境を作る方法

venv はPython 3に標準で付いてくるので、追加インストールは不要です。プロジェクトのディレクトリに入ってから実行します。

python3 -m venv .venv

このコマンドを実行すると、コードと同じ階層に .venv/ フォルダが作成されます。.venv という名前はほぼ業界標準で、先頭のドットのおかげでディレクトリ一覧に埋もれにくく、VS Code などのエディタも自動で認識してくれます。

コマンドが完了すると、このフォルダの中には Python 一式（数十 MB ありますが、これが普通です）と専用の pip が入っています。

仮想環境をアクティベートする

アクティベート（有効化）すると、シェルの PATH が書き換わり、python や pip が .venv/ 内のものを指すようになります。コマンドは OS によって異なります：

# macOS / Linux
source .venv/bin/activate

# Windows (Command Prompt)
.venv\Scripts\activate.bat

# Windows (PowerShell)
.venv\Scripts\Activate.ps1

アクティベート中は、プロンプトの先頭に (.venv) という表示が付きます。今この仮想環境が有効になっている、という目印ですね。この状態で pip install を実行すれば、インストール先はこのプロジェクトだけに限定されます。

作業を終えるときは、deactivate を実行すれば元の状態に戻せます。

deactivate

ターミナルを閉じる前にわざわざ deactivate する必要はありません。シェルを終了すれば同じことです。

パッケージのインストール

仮想環境を有効化した状態で、必要なパッケージを入れていきましょう。

pip install requests
pip install "pandas>=2.0"
pip install --upgrade requests

pip list でインストール済みのパッケージを確認できます。何か消したいときは pip uninstall requests のように実行すればOKです。

インストールされたパッケージの実体は .venv/lib/pythonX.Y/site-packages/ 配下にあります。ここは手で編集するところではなく、あくまで pip に任せるディレクトリです。

requirements.txt で依存関係を固定する

他の人が同じバージョンをインストールできて初めて、プロジェクトは再現可能になります。これを一番手軽に残す方法が requirements.txt です。

pip freeze > requirements.txt

pip freeze を実行すると、インストール済みのパッケージとそのバージョンが一覧で出力されます。生成したファイルは忘れずに git にコミットしておきましょう。

あとは、チームメンバー（あるいは新しいマシンに移行した未来の自分）がリポジトリを clone したときに、次のコマンドで同じ環境を再現できます。

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

3つのコマンドを実行するだけで、同じ環境を再現できます。

よくあるプロジェクトの初期セットアップ

一連の流れを最初から最後まで見てみましょう。

# Create the project folder
mkdir my_tool && cd my_tool

# Create and activate the venv
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install requests rich

# Save them
pip freeze > requirements.txt

# Work on your code...
echo "import requests; print(requests.__version__)" > main.py
python main.py

# When you're done
deactivate

.venv は .gitignore に入れておく

.venv/ フォルダは絶対にコミットしないでください。OS依存のファイルが入っていますし、requirements.txt さえあればいつでも再現できます。

# .gitignore
.venv/
__pycache__/
*.pyc

リポジトリにコミットしてしまうと、サイズが肥大化するうえ、他のマシンで動かなくなったり、自分の環境のOS固有バイナリが漏れ出したりします。

どのPythonバージョンを使うか

デフォルトでは、python3 -m venv .venv を実行すると、シェルが解決する python3 がそのまま使われます。複数のPython(たとえば3.12と3.13)をインストールしている場合は、どれを使うか明示的に指定しましょう。

python3.13 -m venv .venv

venvが一度作られると、その中のインタープリタは固定されます。アクティベート中の仮想環境で python を実行すれば、システム側のPythonが変わっても常にその特定のバージョンが使われます。

うまくいかないときの対処法

よくあるトラブルと解決策をまとめておきます。

• pip install は通るのに import で失敗する。 違うPythonに対してインストールしてしまっています。先に仮想環境をアクティベートしてから pip install を実行し、macOS/Linuxなら which python、Windowsなら where python で確認しましょう。
• アクティベート後に ModuleNotFoundError が出る。 その仮想環境にライブラリが入っていないか、別の仮想環境にインストールされている可能性があります。pip list で現在の環境に実際に入っているパッケージを確認できます。
• Windowsでアクティベートスクリプトが見つからない。 PowerShellが署名なしスクリプトをブロックしているかもしれません。Set-ExecutionPolicy -Scope CurrentUser RemoteSigned を一度実行して、ローカルスクリプトを許可しましょう。
• No module named venv と言われる。 一部のLinuxディストリビューションではvenvが別パッケージになっています。Debian/Ubuntuなら sudo apt install python3-venv でインストールできます。

venv の次のステップ:Poetry、uv、pipenv

venv + pip + requirements.txt の流れに慣れてくると、同じ考え方をもっと使いやすくラップしたツールに出会うはずです。

• Poetry — 仮想環境、依存関係、パッケージングを pyproject.toml ひとつで管理できます。
• uv — pip の高速な代替ツール。仮想環境の管理もこなします。
• pipenv — 「Pipfile + Pipfile.lock」のパターンを広めた、少し古めのツール。

どれも良いツールですが、学習のために必須というわけではありません。まずは素の venv のワークフローに慣れてから、必要に応じて乗り換えていけば十分です。

この章のまとめ

• 本格的なPythonプロジェクトには、必ず専用の仮想環境を用意する。
• python3 -m venv .venv で作成し、アクティベートしてから pip install を自由に使う。
• pip freeze > requirements.txt で依存関係を固定し、そのファイルをコミットする。
• .venv/ フォルダ自体は絶対にコミットしない。
• import周りの挙動がおかしいときは、まずどのPythonがアクティブか確認する。

次回: __main__ パターン

プロジェクトのセットアップとパッケージのインストールができたところで、この章を締めくくる最後のイディオムに進みます。それが if __name__ == "__main__" というガードです。スクリプトとして実行することを想定したPythonファイルにはほぼ必ず登場するもので、次のページで詳しく見ていきます。