Python仮想環境(venv)の作り方と使い方

Pythonで開発を始めると「仮想環境」という言葉を目にします。仮想環境とは、プロジェクトごとに独立したPython環境を作る仕組みです。なぜ必要なのか、どう使うのかを初心者向けに解説します。

仮想環境が必要な理由

Pythonではpipを使って外部ライブラリをインストールしますが、すべてのプロジェクトで同じ場所にインストールすると問題が起きることがあります。

たとえば、プロジェクトAではrequests 2.28を使い、プロジェクトBではrequests 2.31を使いたいとします。仮想環境なしではどちらかのバージョンしかインストールできません。

仮想環境なし（問題あり）
  システム全体: requests 2.31
  プロジェクトA: requests 2.28 が必要 → 動かない
  プロジェクトB: requests 2.31 が必要 → OK

仮想環境あり（解決）
  プロジェクトA/venv: requests 2.28 → OK
  プロジェクトB/venv: requests 2.31 → OK

仮想環境を使えば、プロジェクトごとにライブラリのバージョンを分けて管理できます。

venvの作成と有効化

Pythonにはvenvという仮想環境ツールが標準で付属しています。追加インストールは不要です。

仮想環境の作成

# プロジェクトディレクトリに移動
cd my-project

# 仮想環境を作成（venvという名前のフォルダができる）
python -m venv venv

python -m venv venvの意味は以下の通りです。

python -m venv: venvモジュールを実行する
最後のvenv: 作成するフォルダ名（慣習的にvenvが使われる）

仮想環境の有効化

# macOS / Linux
source venv/bin/activate

# Windows（PowerShell）
venv\Scripts\Activate.ps1

# Windows（コマンドプロンプト）
venv\Scripts\activate.bat

有効化するとターミナルのプロンプトに(venv)が表示されます。

(venv) $ python --version
Python 3.12.0

(venv) $ which python
/path/to/my-project/venv/bin/python

仮想環境の無効化

# 仮想環境を無効化
deactivate

# プロンプトの(venv)が消えたことを確認
$ which python
/usr/bin/python

パッケージの管理

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

# 仮想環境を有効化してからインストール
(venv) $ pip install requests
(venv) $ pip install flask==3.0.0

# インストール済みパッケージの確認
(venv) $ pip list
# Package    Version
# ---------- -------
# Flask      3.0.0
# requests   2.31.0
# ...

requirements.txtで管理する

プロジェクトで使っているパッケージの一覧をファイルに保存し、他の人と共有できます。

# 現在のパッケージ一覧をファイルに出力
(venv) $ pip freeze > requirements.txt

# requirements.txt の中身
Flask==3.0.0
Jinja2==3.1.2
requests==2.31.0
Werkzeug==3.0.1

# requirements.txtからパッケージを一括インストール
(venv) $ pip install -r requirements.txt

チーム開発では、requirements.txtをGitで管理し、各メンバーが同じパッケージ環境を再現できるようにします。

プロジェクトの構成例

仮想環境を含むプロジェクトの典型的な構成を紹介します。

my-project/
  venv/                # 仮想環境（Gitには含めない）
  src/
    main.py
    utils.py
  requirements.txt     # パッケージ一覧（Gitに含める）
  .gitignore
  README.md

.gitignoreには必ずvenv/を追加しましょう。

# .gitignore
venv/
__pycache__/
*.pyc
.env

仮想環境のフォルダは各自のマシンで作り直すものなので、Gitリポジトリに含める必要はありません。

VS Codeとの連携

VS Codeでは仮想環境のPythonインタプリタを選択することで、エディタ内で仮想環境が使われるようになります。

インタプリタの選択方法

VS Codeでプロジェクトフォルダを開く
コマンドパレット（Ctrl+Shift+P / Cmd+Shift+P）を開く
「Python: Select Interpreter」を選択
./venv/bin/python（venvのPython）を選択

設定後はVS Code内のターミナルが自動的に仮想環境を有効化した状態で起動します。

# VS Codeのターミナルで確認
(venv) $ which python
/path/to/my-project/venv/bin/python

よくある間違いと対策

間違い1: 有効化を忘れてインストール

# NG: 仮想環境を有効化せずにインストール
$ pip install requests
# → システムのPythonにインストールされてしまう

# OK: 有効化してからインストール
$ source venv/bin/activate
(venv) $ pip install requests

プロンプトに(venv)が表示されているか、作業の前に毎回確認しましょう。

間違い2: venvフォルダをGitに含めてしまう

# NG: venvごとコミットしてしまう
git add .
git commit -m "プロジェクト追加"
# → venv/以下の大量のファイルがコミットされる

# OK: .gitignoreを先に作る
echo "venv/" >> .gitignore
git add .gitignore
git commit -m ".gitignoreを追加"

間違い3: Pythonのバージョン違い

# python コマンドがPython 2を指している場合がある
python --version
# Python 2.7.x

# 明示的にPython 3を指定
python3 -m venv venv
source venv/bin/activate
python --version
# Python 3.x.x（仮想環境内はpythonでOK）

新しいプロジェクトを始める手順のまとめ

# 1. プロジェクトフォルダを作成
mkdir my-new-project
cd my-new-project

# 2. 仮想環境を作成
python -m venv venv

# 3. 仮想環境を有効化
source venv/bin/activate  # macOS/Linux

# 4. 必要なパッケージをインストール
pip install requests flask

# 5. requirements.txtを生成
pip freeze > requirements.txt

# 6. .gitignoreを作成
echo "venv/" > .gitignore

# 7. Gitリポジトリを初期化
git init
git add .
git commit -m "プロジェクトの初期セットアップ"

仮想環境は最初は面倒に感じるかもしれませんが、プロジェクトが増えてくると必ず必要になります。新しいプロジェクトを始めるときは、まず仮想環境を作ることを習慣にしましょう。