閉じる

Pythonの仮想環境(venv)でプロジェクトごとに環境を分ける方法

Pythonの学習や開発を進めると、プロジェクトごとに必要なライブラリやバージョンが異なります。

そこで頼りになるのが標準機能の仮想環境(venv)です。

本記事では、初心者でも迷わないように、作成から運用のコツ、つまずきやすいポイントまで丁寧に解説します。

目次
  1. venvとは？Pythonの仮想環境の基本
  2. 事前準備(Pythonの確認)
  3. venvの作成手順(プロジェクトごと)
  4. venvの管理と運用のコツ
  5. まとめ

venvとは？Pythonの仮想環境の基本

Pythonの仮想環境(venv)とは、各プロジェクトが使うPython本体とライブラリ群を、他のプロジェクトから独立して管理できる仕組みです。

プロジェクトごとに「箱」を作り、その中に必要なライブラリだけを入れて使うイメージだと理解しやすいです。

仮想環境を使うことで、プロジェクト間のライブラリ衝突を避け、再現性の高い開発が可能になります。

プロジェクトごとに環境を分けるメリット

仮想環境を分ける最大の利点は、依存関係の分離です。

例えば、あるプロジェクトではnumpy==1.26が必要なのに、別のプロジェクトではnumpy==2.xが必要という状況は珍しくありません。

venvならプロジェクト単位で異なるバージョンを共存させられます。

次のような実用的なメリットがあります。

  • 既存プロジェクトが壊れるのを恐れずに最新版ライブラリを試せます。
  • チーム全員が同じ環境を再現しやすくなり、不具合が共有しやすくなります。
  • 管理者権限なしで導入できるため、社内PCや教育環境でも扱いやすいです。

以下は「グローバル環境のまま」困る例と、venvでの解決イメージです。

状況グローバル環境だとvenvなら
複数プロジェクトで違うバージョンのライブラリが必要片方をアップデートするともう片方が壊れる各プロジェクト専用に分離できる
動作確認用に一時的に古いバージョンを入れたいダウングレードが全体に影響その環境だけ切り替え可能
本番と手元の環境差異で不具合何が入っているか把握が難しい依存関係を環境ごとに把握・固定できる

グローバル環境との違い

グローバル環境はOS全体で共有されるPythonとライブラリのセットです。

便利に見えますが、プロジェクト間で影響し合うため、成長するほど管理が難しくなります。

venvは各プロジェクトに閉じた領域を用意し、そこで完結して作業します。

項目グローバル環境venv(仮想環境)
影響範囲全プロジェクトそのプロジェクト内のみ
導入に管理者権限場合により必要不要(ユーザー権限でOK)
再現性低い高い
破壊的変更のリスク高い低い

初心者でも使いやすい理由

venvはPython 3系では標準搭載で、追加ツール無しに導入できます。

コマンドは数個だけで済み、失敗してもフォルダごと削除して作り直せます。

さらに、多くのIDE(VSCodeなど)が自動で検出してくれるため、初めてでも扱いやすいのが大きな魅力です。

事前準備(Pythonの確認)

仮想環境を作る前に、Pythonが正しくインストールされているかを確認します。

Pythonのインストール有無を確認

お使いのOSごとに以下のコマンドでバージョンを確認します。

表示されればインストール済みです。

PowerShell
# Windows (PowerShell 推奨)
py -V
python --version
Batch File
:: Windows (コマンドプロンプト)
py -V
python --version
Shell
# macOS / Linux
python3 --version
python --version

実行例の出力:

text
Python 3.11.9

コマンドが見つからないと出る場合は、Pythonが未インストールかPATH設定が未完了です。

公式サイトやパッケージマネージャ(Homebrew, apt, dnfなど)でインストールしてください。

venvが使えるバージョン(3.3以降)

venvはPython 3.3以降で利用可能です。

Linux系の最小構成ではpython3-venvパッケージが別になっている場合があります。

エラーが出るときは次を参考に導入します。

Shell
# Ubuntu/Debian
sudo apt update
sudo apt install -y python3-venv

# (必要なら) 特定バージョンの venv
# sudo apt install -y python3.11-venv
Shell
# Fedora
sudo dnf install -y python3
# (Fedoraは通常python3にvenvが同梱されています)
Shell
# Arch Linux
sudo pacman -S --needed python

Windowsの公式インストーラ版やmacOSのHomebrew版では、通常そのまま使えます。

プロジェクト用フォルダの作り方

任意の作業ディレクトリでプロジェクトのフォルダを作ります。

フォルダ構成の一例は次のとおりです。

パス用途
myapp/プロジェクトのルート
myapp/.venv/仮想環境(後述の推奨配置)
myapp/src/ソースコード
myapp/tests/テストコード
myapp/README.md説明書き

作成例:

Shell
# macOS / Linux
mkdir -p ~/work/myapp/{src,tests}
cd ~/work/myapp
PowerShell
# Windows (PowerShell)
mkdir $HOME\work\myapp\src, $HOME\work\myapp\tests
cd $HOME\work\myapp

プロジェクト直下に置く仮想環境フォルダ名は「.venv」を強く推奨します。

後述する理由により、IDE連携と共同開発の両面で扱いやすくなります。

venvの作成手順(プロジェクトごと)

ここでは実際に仮想環境を作って有効化し、環境が切り替わったことを確認します。

Windowsの作成コマンド

PowerShellからの手順を示します。

pyランチャは複数バージョンが入っている場合でも適切に選んでくれるため便利です。

PowerShell
# 1) プロジェクトフォルダへ
cd $HOME\work\myapp

# 2) 仮想環境を作成 (.venv フォルダに作られる)
py -m venv .venv
# うまくいかない場合は:
# python -m venv .venv

# 3) 仮想環境を有効化 (プロンプトに(.venv)が付く)
.\.venv\Scripts\Activate.ps1

# 4) 仮想環境の Python / pip を確認
python -V
python -m pip --version

実行例の出力:

text
(.venv) PS C:\Users\you\work\myapp> python -V
Python 3.11.9
(.venv) PS C:\Users\you\work\myapp> python -m pip --version
pip 24.2 from C:\Users\you\work\myapp\.venv\Lib\site-packages\pip (python 3.11)

コマンドプロンプト(cmd.exe)を使う場合の有効化は次のとおりです。

Batch File
:: Windows (cmd.exe の場合)
C:\Users\you\work\myapp> .venv\Scripts\activate.bat

Git Bash等では次のように指定します。

Shell
# Windows + Git Bash の場合
source .venv/Scripts/activate

仮想環境を抜ける(無効化する)には、どのシェルでも次でOKです。

Shell
deactivate
エラー対策

「このシステムではスクリプトの実行が無効になっているため…」と表示された場合は、PowerShellの実行ポリシーをユーザー範囲で緩和します。

PowerShell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
# その後、PowerShellを再起動して再度 Activate.ps1 を実行

macOS/Linuxの作成コマンド

macOSやLinuxではpython3での実行が確実です。

Shell
# 1) プロジェクトフォルダへ
cd ~/work/myapp

# 2) 仮想環境を作成 (.venv フォルダに作られる)
python3 -m venv .venv
# ディストリビューションによっては python -m venv .venv でも可

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

# 4) 仮想環境の Python / pip を確認
python -V
python -m pip --version

実行例の出力:

text
(.venv) myapp % python -V
Python 3.11.9
(.venv) myapp % python -m pip --version
pip 24.2 from /Users/you/work/myapp/.venv/lib/python3.11/site-packages/pip (python 3.11)

仮想環境の保存場所(.venv推奨)

仮想環境の置き場所にはいくつか選択肢があります。

もっとも実務で扱いやすいのが「プロジェクト直下の .venv」です。

置き場所メリット注意点
プロジェクト直下の .venvIDEが自動検出しやすい。プロジェクトと一心同体で分かりやすい。コピーや削除も直感的。ディスク使用量は各プロジェクトごとに発生
プロジェクト直下の venv(非ドット)仕組みは同じ隠しフォルダでなくなるためルートが少し散らかって見える
共有ディレクトリに集約再利用でディスク節約の可能性プロジェクトの移動/共有時にパスがズレやすい、IDE連携が煩雑

VSCodeは.venvやvenvを自動で候補に出してくれます。

チーム開発では.gitignoreに「.venv/」を入れて、リポジトリに含めないのが一般的です。

作成に失敗したときのチェックポイント

失敗例と対処の勘所をまとめます。

どれも初心者がつまずきやすいポイントです。

  • コマンドが見つからない: pythonやpython3、pyのPATHが通っていません。バージョン確認コマンドが動くか再確認してください。
  • ensurepip関連のエラー: Debian/Ubuntu系ではsudo apt install python3-venvが必要なことがあります。
  • Windowsのスクリプト実行制限: 前述のSet-ExecutionPolicyで回避します。
  • 作成はできたが有効化で失敗: シェル種類に適したスクリプトを使っているか確認します(PowerShellはActivate.ps1、cmdはactivate.bat、bash/zshはbin/activate)。
  • どのPythonを使っているか不安: 次のワンライナーで実行ファイルパスを確認します。
Shell
python -c "import sys; print(sys.executable)"
実行結果
/Users/you/work/myapp/.venv/bin/python

venvの管理と運用のコツ

作って終わりではなく、日々の使い方やメンテナンスでつまずきにくくするのが大切です。

仮想環境の削除方法

仮想環境はフォルダを丸ごと削除すれば消えます。

事前に有効化している場合はdeactivateで抜けてから削除します。

Shell
# macOS / Linux
deactivate  # 必要なら
rm -rf .venv
PowerShell
# Windows (PowerShell)
deactivate  # 必要なら
Remove-Item -Recurse -Force .venv
Batch File
:: Windows (cmd.exe)
deactivate  &  rmdir /s /q .venv

必要になれば、同じ手順で再作成できます。

削除と作り直しの容易さがvenvの強みです。

プロジェクトをコピーするときの注意点

プロジェクトフォルダごと別PCに移したり共有するとき、.venvはコピーしないのが原則です。

OSやパスが違うと動かなくなるため、移行先で再作成します。

そのうえで必要なライブラリを再インストールします(ライブラリ一覧の保存と復元は別記事で扱います)。

Git運用では.gitignoreに.venv/を入れておくと安全です。

よくあるエラーと簡単な対処法

初心者が遭遇しやすいエラーと、最短で解決するコツを挙げます。

  • pipがグローバルを見てしまう/見つからない
    いつでもpython -m pipの形式で実行すれば、pythonが指す環境のpipが確実に使われます。
Shell
python -m pip install requests
python -m pip list
有効化スクリプトが見つからない

WindowsでPowerShellなら..venv\Scripts\Activate.ps1、cmdなら.venv\Scripts\activate.bat、macOS/Linuxならsource .venv/bin/activateです。

入力ミスや大文字小文字を確認します。

プロンプトに(.venv)が付かない

有効化に失敗しています。

現在のシェルの種類、エラーメッセージ、実行権限(Unixならsourceを使っているか)を確認します。

ライブラリが見つからない(ModuleNotFoundError)

その仮想環境内でインストールされていない可能性があります。

有効化後にpython -m pip install パッケージ名で導入します。

LinuxでNo module named venv


Debian/Ubuntu系ではsudo apt install python3-venvを実行してください。

環境が切り替わったかを確認するサンプルコード

仮想環境の実行ファイルパスや、サイトパッケージの場所を出力して確認します。

Python
# env_check.py
# 仮想環境が正しく有効化されているかを確認するサンプル
import sys
import site
import platform

print("# Python 実行ファイル")
print(sys.executable)  # 例: /path/to/project/.venv/bin/python

print("\n# バージョン情報")
print(platform.python_version())

print("\n# site-packages の検索パス")
for p in site.getsitepackages():
    print(p)

print("\n# 仮想環境が想定どおりかの簡易チェック")
is_venv = (hasattr(sys, 'base_prefix') and sys.prefix != getattr(sys, 'base_prefix', sys.prefix))
print("venv内:", is_venv)
Shell
# 仮想環境を有効化した状態で実行
python env_check.py
実行結果
# Python 実行ファイル
/Users/you/work/myapp/.venv/bin/python

# バージョン情報
3.11.9

# site-packages の検索パス
/Users/you/work/myapp/.venv/lib/python3.11/site-packages

# 仮想環境が想定どおりかの簡易チェック
venv内: True

実行ファイルやsite-packagesのパスに「.venv」が含まれていれば成功です。

まとめ

本記事では、Pythonの仮想環境(venv)を使ってプロジェクトごとに依存関係を安全に分離する方法を解説しました。

Python 3.3以降なら標準で利用でき、作成(python -m venv .venv)、有効化、確認、削除の流れはどれも短いコマンドで実行できます。

特にプロジェクト直下の「.venv」配置はIDE連携やチーム開発で利便性が高く、トラブルも少なくなります。

うまくいかない場合は、実行ポリシーやpython3-venvの不足など典型的な原因を疑い、本文のチェックポイントを参照してください。

仮想環境を習慣化すれば、学習から本格開発まで、安定して再現性の高いPython開発が実現できます。

Python 実践TIPS - 開発環境とツール
この記事を書いた人
エーテリア編集部
エーテリア編集部

人気のPythonを初めて学ぶ方向けに、文法の基本から小さな自動化まで、実際に手を動かして理解できる記事を書いています。

クラウドSSLサイトシールは安心の証です。

URLをコピーしました！