仮想環境したい（`venv`）

// プロジェクトルートを作成する／移動する
$ mkdir -p path/to/your_project
$ cd path/to/your_project

// 仮想環境を作成する
$ python3 -m venv .venv

// 仮想環境を有効にする
$ source .venv/bin/activate
(.venv) $

// 仮想環境を無効にする
(.venv) $ deactivate
$

venvパッケージで、仮想環境を作成できます。 Python3.3以降に付属する標準モジュールです。コマンドではpython3 -m venvの形でモジュールとして呼び出す必要があります。

注釈

Pythonのパッケージは、プロジェクトごとに異なるバージョンが必要になることがあります。システム全体にインストールすると、複数のプロジェクト間でバージョンの競合が起きる可能性があります。

この問題を避けるため、最近のPython環境では、システムグローバルにパッケージをインストールすることは非推奨となっています。代わりに、仮想環境を使って各プロジェクトに独立した環境を用意することが推奨されています。これにより、プロジェクト間の依存関係の競合を防ぎ、環境を再現性よく管理できます。

バージョンを切り替えたい

// Python3.11の仮想環境
$ python3.11 -m venv .venv
$ source .venv/bin/activate
(.venv) $ python --version
Python 3.11.16

// Python3.12の仮想環境
$ python3.12 -m venv .venv
$ source .venv/bin/activate
(.venv) $ python --version
Python 3.12.7

venvモジュールを呼び出すときに python3.11 -m venv、 python3.12 -m venv、のようにPythonの実行環境のバージョンを指定します。

注釈

venvモジュール自体には、Python実行環境の切り替え機能はありません。

最近では、これらの機能が統合された uvパッケージを利用するのがオススメです。

システムパッケージを使いたい（`--system-site-packages`）

$ python3 -m venv --system-site-packages .venv

--system-site-packagesオプションで、作成した仮想環境からシステムのPython環境にアクセスできるようにできます。 PyROOTのように、システムのPython環境にインストールされてしまうパッケージを仮想環境から利用したい場合に必要です。

表示名を変更したい（`--prompt`）

$ python3 -m venv --prompt myproj .venv
$ source .venv/bin/activate
(myproj) $

--promptオプションで、仮想環境を有効化したときのプロンプト表示を変更できます。デフォルトではディレクトリ名（.venvの場合は親ディレクトリ名）が使われますが、複数のプロジェクトを並行して開いているときに、区別しやすくなります。

他ツールと比較したい

venvとその他の仮想環境・パッケージ管理ツールを比較してみました。目的やプロジェクトの規模に応じて適切なツールを選ぶことが重要です。ただし、これからはじめるプロジェクトはvenvかuvを選ぶのがよいと思います。

ツール名	推奨度	用途	特長
`venv`	★★★★★	基本的な仮想環境	Python3.3以降の標準。シンプルで軽量。初心者向け
`uv`	★★★★★	統合的なパッケージ管理	オススメの最新ツール。`venv`と`pip`の機能を統合して高速化
`poetry`	★★★★	パッケージ開発	複雑なプロジェクトやパッケージ公開時に便利
`pyenv`	★★★	Python実行環境管理	複数Pythonバージョンの管理に特化。`venv`と併用
`virtualenv`	★★★	高度なカスタマイズ	`venv`より柔軟。現在は`uv`の方がオススメ
`pipenv`	★★	プロジェクト依存管理	`Pipfile`を使用。開発・メンテナンスが減少傾向

ツールへの依存をできるだけ減らしたい場合は、標準モジュールのvenvで仮想環境を作成し、pipでパッケージをインストールする組み合わせがベストです。

モダンなプロジェクト管理をしたい場合はuvもしくはpoetryを利用すると便利です。これらのツールはpyproject.tomlで依存関係を管理できるため、環境構築を効率化し、再現性を高めることができます。複数のPythonバージョンを扱う必要がある場合は、実行環境と仮想環境を一括管理できるuvがオススメです。

注釈

virtualenvはPython2系とPython3系が混在する時期に活躍したようですが、現在はvenvで十分なようです（virtualenv自体は今もメンテナンスが続いており、venvより高速という特長もあります）。 pipenvは2017年ころに人気がありました。 2018年末から2020年にかけて開発が停滞した時期もありましたが、現在はメンテナンスが再開されています。とはいえ、モダンなプロジェクト管理をしたい場合はpoetryやuvを使うことをオススメします。

また、pyenvでPythonのバージョンを管理して、 venvで仮想環境を作成する組み合わせもあるようですが、こちらもuvが断然オススメです。

仮想環境したい（venv）