Pythonで開発をしていると、こんな悩みに直面することってありませんか?
- プロジェクトごとに使うパッケージがバラバラで管理が大変…
- 他の人の環境とパッケージが微妙に異なっていてトラブルが起きた…
- グローバルにパッケージを入れて環境がごちゃごちゃになってしまった…
こうした悩みを解決してくれるのが、Pythonの仮想環境(virtual environment)です。
この記事では、Pythonの標準機能である「venv
」を使った仮想環境の構築方法について、以下の内容をわかりやすく解説します。
- venvとは?
- 仮想環境構築でよく使うコマンド
- venvで仮想環境を作る方法
- 仮想環境を有効化する方法(activate)
- 仮想環境を無効化する方法(deactivate)
- 仮想環境を削除する方法
- 仮想環境にパッケージをインストールする方法
- 仮想環境にインストールしたパッケージを確認する方法
- 仮想環境にインストールしたパッケージの詳細情報を確認する方法
- 仮想環境にインストールしたパッケージの一覧を保存・再現する方法
- 仮想環境にインストールしたパッケージの依存関係のグラフ(ツリー)を確認する方法
venvとは?
venvはPythonに標準で用意されている仮想環境作成ツールです。
通常、Pythonにパッケージをインストールすると、すべてのプロジェクトで共通の場所にパッケージが追加されます。そのため、「あるプロジェクトで必要なパッケージのバージョン」と「別のプロジェクトで必要なパッケージのバージョン」がぶつかってしまうことがあり、トラブルの原因になります。
そこで便利なのがvenvです。
venvを使うと、プロジェクト専用の「仮想環境(Pythonやパッケージが分離された空間)」を作ることができます。これにより、他のプロジェクトに影響を与えることなく、自分の好きなパッケージやバージョンを自由にインストールして使うことができます。
仮想環境を使うことで以下のようなメリットがあります。
- 他のプロジェクトとパッケージのバージョンが衝突しない
- プロジェクトに必要なパッケージだけをクリーンに管理できる
- チーム全員が同じ環境を再現しやすい
特にチーム開発では、仮想環境に入れたパッケージの情報(requirements.txt
など)を共有することで、誰でも同じ環境をすぐに再現できるようになり、とても便利です、
仮想環境構築でよく使うコマンド
以下に仮想環境構築ででよく使うコマンドを表形式でまとめました(後ほど各コマンドについて詳しく説明します)。
コマンド | 説明 |
---|---|
python -m venv .venv | 仮想環境を作成 |
source .venv/bin/activate | 仮想環境を有効化(mac/Linux) |
.venv\Scripts\Activate.ps1 | 仮想環境を有効化(Windows) |
deactivate | 仮想環境を終了 |
pip install パッケージ名 | パッケージのインストール |
pip freeze > requirements.txt | パッケージ一覧を保存 |
pip install -r requirements.txt | パッケージを再現(インストール) |
rm -rf .venv | 仮想環境を削除(mac/Linux) |
rd /s /q .venv | 仮想環境を削除(Windows) |
venvで仮想環境を作る方法
事前準備
新しくPythonプロジェクトを始める場合、まず作業用のディレクトリ(フォルダ)を作り、移動しましょう。以下のコマンドではtest-project
ディレクトリを作成し、その作成したディレクトリに移動しています。
mkdir test-project && cd test-project
仮想環境を作成するには、以下のコマンドを実行します。
python -m venv .venv
.venv
は仮想環境のフォルダ名です。
python -m venv
は仮想環境を作るためのコマンド.venv
は「仮想環境をこの名前でこの場所に作ってね」という指示です。
多くのPython開発者は、プロジェクトのルートディレクトリに.venv
という名前で作ることが一般的です(慣例です)。
コマンドを実行すると、以下のようなディレクトリ構成になります。
my-project/
├── .venv/ ← 仮想環境がここにできる
└── (自分で作ったPythonコードや設定ファイルなど)
補足
python -m venv .venv
を実行すると、今使っているPythonのバージョンで仮想環境が作られます。もし特定のPythonバージョンで仮想環境を作りたい場合は、pyenv
を併用して目的のバージョンをインストール・切り替えてからpython -m venv .venv
を実行しましょう。
仮想環境を有効化する方法(activate)
Pythonでの開発では、作成した仮想環境を有効化(アクティブ化)してから作業を始めるのが基本です。有効化することで、pip install
やpython
コマンドなどが、その仮想環境の中だけで動くようになります。
仮想環境のフォルダが.venv
だった場合、以下のコマンドで仮想環境を有効化できます。
# macOS / Linux の場合
source .venv/bin/activate
# Windows(PowerShell)の場合
.venv\Scripts\Activate.ps1
# Windows(コマンドプロンプト)の場合
.venv\Scripts\activate.bat
仮想環境を有効化すると、いかに示すように、ターミナル(またはコマンドプロンプト)の左側に仮想環境名が表示されます。
(.venv) user01@Ubuntu:~/test-project$
この状態になっていれば、仮想環境の中に入っているということです。
仮想環境を無効化する方法(deactivate)
仮想環境を使い終わったら、「元の環境に戻る」=無効化(deactivate)を行います。これにより、仮想環境の影響を受けない、通常のPython環境に戻ります。
仮想環境を無効化するには、以下のコマンドを実行します。
deactivate
これで仮想環境から抜けて、元のPython環境に戻ります。プロンプトから(.venv)
の表示も消えます。
exit
やCtrl + D
でシェル自体を閉じることでも仮想環境から抜けられます。ただし、この方法だとシェルごと終了するので、ターミナルをそのまま使い続けたいときはdeactivate
を使う方が便利です。
仮想環境を削除する方法
Pythonの仮想環境は、プロジェクト内に作成される.venv
フォルダにすべての情報が保存されます。そのため、仮想環境を削除したい場合は、フォルダごと削除するだけでOKです。
仮想環境のフォルダが.venv
だった場合、以下のコマンドで仮想環境を削除できます。
# macOS / Linux の場合
rm -rf .venv
# Windows(コマンドプロンプト)の場合
Remove-Item -Recurse -Force .venv
# Windows(コマンドプロンプト)の場合
rd /s /q .venv
補足
- 仮想環境を削除しても、自分の作成したPythonコードや設定ファイルには影響ありません。
.venv
フォルダ内に入っていたパッケージ・依存関係・Pythonの実行ファイルなどはすべて削除されます。- 再度仮想環境を作るときは、もう一度
python -m venv .venv
からやり直しましょう。
仮想環境にパッケージをインストールする方法
仮想環境を有効化した状態で、pip
コマンドを使ってパッケージをインストールできます。
pipenv install numpy
このとき、パッケージはグローバル環境ではなく、仮想環境(.venv
ディレクトリ)内にのみインストールされます。
バージョンを指定してインストールする方法
パッケージのバージョンを明示的に指定したいときは、pip
で以下のように指定できます。
pip install numpy==2.3.2 # 完全に固定(指定バージョン以外はインストールされない)
pip install numpy~=2.3 # 2.3以上かつ2.4未満(推奨される指定方法)
==
はバージョンを完全に固定します。再現性は高いですが、バージョン更新されません。~=
は「メジャーバージョンロック」と呼ばれ、例えば~=2.3
は>=2.3.0, <2.4.0
と同じ意味になります。将来的なマイナーバージョンの更新が許容され、柔軟性があります。
仮想環境にインストールしたパッケージを確認する方法
仮想環境内でどんなパッケージがインストールされているのかを確認したいときは、以下のコマンドを実行します。
pip list
これは、現在のPython環境にインストールされているすべてのパッケージとそのバージョンを一覧表示します。
実行結果の例
(.venv) user01@Ubuntu:~/test-project$ pip list
Package Version
----------- -------
autopep8 2.3.2
flake8 7.3.0
iniconfig 2.1.0
mccabe 0.7.0
numpy 2.3.2
packaging 25.0
pip 24.0
pluggy 1.6.0
pycodestyle 2.14.0
pyflakes 3.4.0
Pygments 2.19.2
pytest 8.4.1
仮想環境にインストールしたパッケージの詳細情報を確認する方法
特定のパッケージの詳細情報を確認したいときは、以下のコマンドを実行します。
# numpyの場合
pip show numpy
実行結果の例
(.venv) user01@Ubuntu:~/test-project$ pip show numpy
Name: numpy
Version: 2.3.2
Summary: Fundamental package for array computing in Python
Home-page: https://numpy.org
Author: Travis E. Oliphant et al.
Author-email:
License:
...
(略)
...
Location: /home/user01/work/test-project/.venv/lib/python3.12/site-packages
Requires:
Required-by:
インストール先のパスや依存関係の情報も確認できます。
パッケージの一覧を保存・再現する方法
プロジェクトで使っているパッケージの一覧をテキストファイル(requirements.txt
)に保存しておきたい場合は、以下のコマンドを実行します。
pip freeze > requirements.txt
このコマンドで、現在の仮想環境にインストールされているすべてのパッケージとそのバージョン情報が、requirements.txt
というファイルに書き出され、チームメンバーやCI/CDで同じ環境を再現しやすくなります。
出力例(requirements.txt)
autopep8==2.3.2
flake8==7.3.0
iniconfig==2.1.0
mccabe==0.7.0
numpy==2.3.2
packaging==25.0
pluggy==1.6.0
pycodestyle==2.14.0
pyflakes==3.4.0
Pygments==2.19.2
pytest==8.4.1
requirements.txt
から仮想環境を再現するには、以下のコマンドを実行します。
pip install -r requirements.txt
これにより、requirements.txt
に書かれている内容通りに、すべてのパッケージがインストールされます。
仮想環境にインストールしたパッケージの依存関係のグラフ(ツリー)を確認する方法
Pythonのプロジェクトでは、あるパッケージが別のパッケージに依存していることがあります。それをツリー形式で可視化したいときに便利なのが、pipdeptree
というツールです。
まず、仮想環境を有効にした状態でpipdeptree
を以下のコマンドでインストールします。
pip install pipdeptree
その後、以下のコマンドを実行します。
pipdeptree
これだけで、現在の仮想環境にインストールされているパッケージの依存関係がツリー構造で表示されます。
実行結果の例
(.venv) user01@Ubuntu:~/test-project$ pipdeptree
autopep8==2.3.2
└── pycodestyle [required: >=2.12.0, installed: 2.14.0]
flake8==7.3.0
├── mccabe [required: >=0.7.0,<0.8.0, installed: 0.7.0]
├── pycodestyle [required: >=2.14.0,<2.15.0, installed: 2.14.0]
└── pyflakes [required: >=3.4.0,<3.5.0, installed: 3.4.0]
numpy==2.3.2
pipdeptree==2.28.0
├── packaging [required: >=24.1, installed: 25.0]
└── pip [required: >=24.2, installed: 25.2]
pytest==8.4.1
├── iniconfig [required: >=1, installed: 2.1.0]
├── packaging [required: >=20, installed: 25.0]
├── pluggy [required: >=1.5,<2, installed: 1.6.0]
└── Pygments [required: >=2.7.2, installed: 2.19.2]
表示内容の見方
- 各パッケージ名とそのバージョンが表示される
- 下にある行は「どのパッケージに依存しているか」
[required: ...]
は要求されているバージョン[installed: ...]
は実際にインストールされているバージョン
本記事のまとめ
Pythonの標準機能である「venv
」について、以下の内容を説明しました。
- venvとは?
- 仮想環境構築でよく使うコマンド
- venvで仮想環境を作る方法
- 仮想環境を有効化する方法(activate)
- 仮想環境を無効化する方法(deactivate)
- 仮想環境を削除する方法
- 仮想環境にパッケージをインストールする方法
- 仮想環境にインストールしたパッケージを確認する方法
- 仮想環境にインストールしたパッケージの詳細情報を確認する方法
- 仮想環境にインストールしたパッケージの一覧を保存・再現する方法
- 仮想環境にインストールしたパッケージの依存関係のグラフ(ツリー)を確認する方法
お読み頂きありがとうございました。