VSCodeでpyenvを使うと、プロジェクトごとに異なるPythonのバージョンを切り替えながら開発できます。
たとえば、あるプロジェクトではPython 3.11を使い、別のプロジェクトではPython 3.12を使うといった管理が可能です。
ただし、VSCode自体がpyenvを管理するわけではありません。
基本的には、pyenvで使用するPythonのバージョンを指定し、そのPython環境をVSCodeのインタープリターとして選択する形になります。
さらに実務では、pyenvとvenvを組み合わせることで、Python本体のバージョンとライブラリ環境をそれぞれ分離して管理できます。
pyenvとは
複数のPythonバージョンを管理するツール
pyenvは、1台のPCに複数のPythonをインストールし、状況に応じて使用するバージョンを切り替えられるツールです。
たとえば、次のようなPythonを同じPC内に共存させられます。
Python 3.10
Python 3.11
Python 3.12
Python 3.13
プロジェクトごとに使用するPythonを変更できるため、古いシステムの保守と新しいシステムの開発を同じPCで行う場合にも便利です。
pyenvはshimを使ってPythonを切り替える
pyenvでは、shimsと呼ばれる仕組みを利用して、実行するPythonを切り替えます。
シェルでpythonコマンドを実行すると、pyenvのshimを経由し、現在設定されているPythonが呼び出されます。
そのため、pyenvを利用するときは、PATHやシェル設定を正しく行うことが重要です。
VSCodeでpyenvを使うメリット
プロジェクトごとにPythonのバージョンを指定できる
pyenvでは、プロジェクトディレクトリ単位でPythonのバージョンを指定できます。
たとえば、次のような使い分けが可能です。
project-a/
Python 3.11
project-b/
Python 3.12
project-c/
Python 3.13
使用するPythonのバージョンがプロジェクトごとに異なる場合でも、簡単に切り替えられます。
システムPythonを直接変更する必要がない
macOSやLinuxでは、OSや各種ツールがシステム側のPythonを利用している場合があります。
そのため、システムPythonを直接変更すると、OSやほかのアプリケーションへ影響する可能性があります。
pyenvを利用すれば、ユーザー環境内に別のPythonをインストールできるため、システムPythonを変更せずに開発環境を整えられます。
チームでPythonのバージョンを統一しやすい
pyenv localを実行すると、通常はプロジェクトディレクトリに.python-versionファイルが作成されます。
たとえば、次のような構成になります。
sample-project/
├── .python-version
├── app.py
└── requirements.txt
.python-versionには、使用するPythonのバージョンが記録されます。
3.12.x
このファイルを利用することで、プロジェクト内で使用するPythonのバージョンを分かりやすく管理できます。
VSCodeでpyenvを使うために必要なもの
VSCodeとPython拡張機能を用意する
VSCodeでPythonを開発する場合は、基本的に以下を用意します。
VSCode
Python拡張機能
pyenv
VSCodeでは、Microsoftが提供しているPython拡張機能を導入することで、Pythonインタープリターの選択やコード実行、デバッグなどが行えるようになります。
pyenvとvenvを組み合わせると管理しやすい
実際の開発では、pyenvだけでなくvenvも併用すると環境を整理しやすくなります。
それぞれの役割は異なります。
pyenv
↓
Python本体のバージョン管理
venv
↓
Pythonパッケージ環境の分離
たとえば、pyenvでPython 3.12系を選択し、そのPythonを使ってvenvの仮想環境を作成します。
pyenv
↓
Python 3.12
↓
venv
↓
.venv
↓
VSCode
この構成にすると、Python本体とライブラリ環境を別々に管理できます。
pyenvをインストールする方法
macOSでpyenvをインストールする
macOSでHomebrewを利用している場合は、次のコマンドでpyenvをインストールできます。
brew install pyenv
インストール後は、次のコマンドで確認できます。
pyenv --version
バージョン情報が表示されれば、pyenv自体はインストールされています。
Linuxでpyenvをインストールする
Linuxでは、公式のインストーラースクリプトを利用できます。
curl -fsSL https://pyenv.run | bash
ただし、pyenvでPythonをインストールするときは、ソースコードからPythonをビルドする場合があります。
そのため、コンパイラーやOpenSSL、zlibなどの開発用パッケージが必要になることがあります。
使用しているLinuxディストリビューションに応じて、必要な依存パッケージを事前に導入しておきましょう。
WindowsではWSLまたはpyenv-winを利用する
本家のpyenvは、通常のWindows環境をネイティブでは正式にサポートしていません。
Windowsで利用する場合は、主に次の方法があります。
Windows
├── WSL + 本家pyenv
└── Windowsネイティブ + pyenv-win
Linuxに近いPython開発環境を構築したい場合は、WSL上に本家pyenvをインストールする方法が便利です。
なお、WSL上でpyenvを使った場合にインストールされるのは、Windows版PythonではなくLinux版Pythonです。
pyenvのシェル設定を行う
zshの場合
macOSなどでzshを利用している場合は、~/.zshrcなどにpyenvの設定を追加します。
代表的な設定例は次のとおりです。
export PYENV_ROOT="$HOME/.pyenv"
[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init - zsh)"
設定後は、ターミナルを開き直すか、シェルを再起動します。
exec "$SHELL"
環境によっては、.zprofileや.zloginへの設定も必要になる場合があります。
bashの場合
bashを利用している場合は、.bashrcや.bash_profile、.profileなどに設定を追加します。
代表的な設定例は次のとおりです。
export PYENV_ROOT="$HOME/.pyenv"
[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init - bash)"
どの設定ファイルが読み込まれるかはOSやシェルの起動方法によって異なるため、環境に合わせて設定する必要があります。
pyenv init –installを利用する方法もある
現在のpyenvでは、シェル設定を補助するコマンドとして、次のような方法も利用できます。
pyenv init --install
インストール方法によっては、次のように実行することもあります。
~/.pyenv/bin/pyenv init --install
手動でシェル設定を記述する方法とあわせて覚えておくと便利です。
pyenvでPythonをインストールする
インストール可能なPythonを確認する
pyenvで利用できるPythonのバージョンは、次のコマンドで確認できます。
pyenv install --list
短縮形も利用できます。
pyenv install -l
Pythonのパッチバージョンは更新されるため、実際にインストールするときはこの一覧から利用可能なバージョンを確認するのがおすすめです。
Pythonをインストールする
利用したいPythonを確認したら、バージョンを指定してインストールします。
pyenv install 3.x.x
たとえば、一覧に表示されているPython 3.12系のバージョンを指定します。
インストール済みのPythonは、次のコマンドで確認できます。
pyenv versions
pyenvでPythonのバージョンを切り替える
pyenv globalで基本のPythonを指定する
ユーザー環境で基本的に利用するPythonは、pyenv globalで指定できます。
pyenv global 3.x.x
設定後は、次のように確認します。
python --version
pyenv localでプロジェクト用Pythonを指定する
VSCodeでプロジェクトごとにPythonを使い分ける場合は、pyenv localが便利です。
まず、プロジェクトディレクトリへ移動します。
cd ~/projects/sample
次に、使用するPythonを指定します。
pyenv local 3.x.x
すると、通常は次のファイルが作成されます。
.python-version
以降、そのディレクトリや配下では、指定したPythonが優先されます。
pyenv shellで一時的に切り替える
現在開いているシェルだけPythonを切り替えたい場合は、pyenv shellを利用できます。
pyenv shell 3.x.x
この設定は一時的なもので、別のシェルには基本的に引き継がれません。
解除するときは、次のコマンドを利用できます。
pyenv shell --unset
なお、pyenv shellを利用するには、pyenvのシェル統合が正しく設定されている必要があります。
pyenvのPythonバージョンが決まる仕組み
設定には優先順位がある
pyenvでは、複数の設定をもとに使用するPythonが決定されます。
初心者向けに簡略化すると、次のような優先順位で考えると分かりやすいでしょう。
pyenv shell
↓
pyenv local
↓
pyenv global
より厳密には、pyenv shellで設定されるPYENV_VERSION環境変数や、.python-versionなどが参照されます。
現在選択されているPythonを確認する場合は、次のコマンドが便利です。
pyenv version
たとえば、次のように表示されます。
3.x.x (set by /path/to/project/.python-version)
どの設定によってPythonが選ばれているのかも確認できます。
VSCodeにPython拡張機能をインストールする
拡張機能画面からPythonを検索する
VSCodeでPythonを開発する場合は、Microsoftが提供しているPython拡張機能をインストールします。
VSCodeの拡張機能ビューを開き、Pythonと検索してください。
WindowsやLinuxでは、次のショートカットでも拡張機能ビューを開けます。
Ctrl + Shift + X
MicrosoftのPython拡張機能をインストールすると、インタープリターの選択、コード実行、デバッグなどが利用できるようになります。
VSCodeでpyenvのPythonを選択する
Python: Select Interpreterを開く
VSCodeでプロジェクトを開いたら、コマンドパレットから使用するPython環境を選択します。
WindowsやLinuxでは、次のショートカットでコマンドパレットを開けます。
Ctrl + Shift + P
macOSでは次のショートカットです。
Command + Shift + P
続いて、次のコマンドを検索します。
Python: Select Interpreter
pyenvでインストールしたPythonを選択する
一覧にpyenvのPythonが表示された場合は、使用したいものを選択します。
macOSやLinuxでは、たとえば次のような場所にPythonが存在します。
~/.pyenv/versions/3.x.x/bin/python
現在pyenvが利用しているPythonの場所を確認したい場合は、次のコマンドを使えます。
pyenv which python
VSCodeで同じPythonを選択すれば、pyenvで管理しているPython環境を利用できます。
参考サイト
VSCodeでPythonインタープリターを選択・切り替える方法：pyenv・venv・mise対応 – Engineering Tech Dojo
pyenvとvenvを組み合わせる方法
pyenvでPython本体を指定する
まず、プロジェクトを作成します。
mkdir sample-project
cd sample-project
続いて、pyenvで使用するPythonを指定します。
pyenv local 3.x.x
Pythonが切り替わっているか確認します。
python --version
venvで仮想環境を作る
次に、選択したPythonを使って仮想環境を作成します。
python -m venv .venv
プロジェクトは次のような構成になります。
sample-project/
├── .python-version
├── .venv/
└── app.py
macOSやLinuxでは、次のコマンドで仮想環境を有効化できます。
source .venv/bin/activate
WindowsのPowerShellでは、環境によって次のように実行します。
.venv\Scripts\Activate.ps1
VSCodeでは.venvを選択する
仮想環境を作成したら、VSCodeで再び次のコマンドを実行します。
Python: Select Interpreter
そして、プロジェクト内の.venvを選択します。
macOSやLinuxでは、たとえば次のようなPythonです。
.venv/bin/python
この構成にすると、pyenvではPython本体のバージョンを管理し、venvではプロジェクト固有のライブラリを管理できます。
VSCodeで使用中のPythonを確認する
python –versionでバージョンを確認する
VSCodeの統合ターミナルを開き、次のコマンドを実行します。
python --version
想定しているPythonのバージョンが表示されているか確認します。
実行ファイルの場所を確認する
macOSやLinuxでは、次のコマンドでPythonの場所を確認できます。
which python
pyenv側から確認する場合は、次のコマンドも利用できます。
pyenv which python
venvを使用している場合は、次のようなパスになることがあります。
/path/to/project/.venv/bin/python
pyenvのPythonを直接利用している場合は、次のようになります。
~/.pyenv/versions/3.x.x/bin/python
VSCodeがpyenvを認識しない場合の対処法
VSCodeを再起動する
pyenvをインストールした直後やPATHを変更した直後は、起動済みのVSCodeへ設定が反映されていない場合があります。
一度VSCodeを完全に終了し、再起動してみましょう。
pyenvが使えるか確認する
VSCodeの統合ターミナルで、次のコマンドを実行します。
pyenv --version
認識されない場合は、VSCodeより先にシェル設定やPATHを確認する必要があります。
次のコマンドも役立ちます。
which pyenv
pyenv root
pyenv versions
pyenv versionで現在の設定を確認する
現在どのPythonが選択されているか確認する場合は、次のコマンドが便利です。
pyenv version
さらに、実際に利用されるPythonの場所は次のコマンドで確認できます。
pyenv which python
PATHを確認する
次のコマンドを実行します。
which python
期待しているpyenv配下ではなく、たとえば次のようになっている場合があります。
/usr/bin/python
この場合、pyenvのshimsがPATHで正しく優先されていない可能性があります。
シェル設定を見直してください。
Python: Select Interpreterから手動で指定する
pyenv自体が正常に動いていても、VSCodeがPython環境を自動検出できないことがあります。
その場合は、コマンドパレットから次を実行します。
Python: Select Interpreter
目的のPythonや.venvを手動で選択してください。
新しい統合ターミナルを開く
VSCodeでインタープリターを変更しても、すでに開いている統合ターミナルの環境が即座に切り替わらない場合があります。
その場合は、既存のターミナルを閉じ、新しい統合ターミナルを開いて確認してください。
VSCodeにはPython環境をターミナルで自動的に有効化する設定がありますが、設定内容や拡張機能の状態によって動作が異なる場合があります。
ターミナルからVSCodeを起動する
PATHの設定がVSCodeへうまく反映されない場合は、プロジェクトディレクトリから次のように起動すると改善することがあります。
code .
ただし、code .から起動することはpyenvを使うための必須条件ではありません。
PATHや環境変数に問題がある場合のトラブルシューティング方法として考えるとよいでしょう。
WindowsでVSCodeとpyenvを使う場合
WSLで本家pyenvを使う
Windowsで本家pyenvを利用したい場合は、WSL環境を使う方法があります。
構成としては、次のようになります。
Windows
↓
WSL
↓
pyenv
↓
Python
↓
venv
↓
VSCode
この場合、pyenvやPythonはWSL側へインストールします。
WSL上で動作するため、Linux版Pythonを利用する環境になります。
Windowsネイティブではpyenv-winを検討する
Windowsネイティブ環境でPythonのバージョン管理をしたい場合は、pyenv-winという別プロジェクトがあります。
本家pyenvとpyenv-winは同じものではないため、インストール方法や一部の使い方が異なる点には注意しましょう。
VSCode・pyenv・venvの役割を整理する
pyenvはPython本体を管理する
pyenvが担当するのは、基本的にPython本体のバージョン管理です。
pyenv
↓
Python 3.11
Python 3.12
Python 3.13
venvはパッケージ環境を分離する
venvは、プロジェクトごとにPythonパッケージのインストール先を分離します。
venv
↓
.venv/
↓
Django
Flask
NumPy
pandas
など
VSCodeは使用するPython環境を選択する
VSCodeでは、Python拡張機能を通じて使用するPythonインタープリターを選択します。
そのため、実務では次の役割分担を意識すると分かりやすくなります。
pyenv
→ Python本体のバージョンを選ぶ
venv
→ プロジェクトごとのパッケージ環境を作る
VSCode
→ .venvのPythonをインタープリターとして利用する
VSCodeでpyenvを使う場合のおすすめ構成
プロジェクト構成例
一般的なPythonプロジェクトでは、次のような構成にすると管理しやすいでしょう。
project/
├── .python-version
├── .venv/
├── src/
├── tests/
├── requirements.txt
└── README.md
.python-versionではpyenvのPythonバージョンを管理し、.venvではプロジェクト固有のPythonパッケージを管理します。
環境構築の基本的な流れ
実際の手順は、次のように整理できます。
mkdir project
cd project
pyenv install 3.x.x
pyenv local 3.x.x
python -m venv .venv
macOSやLinuxでは、仮想環境を有効化します。
source .venv/bin/activate
必要であれば、pipを更新します。
python -m pip install --upgrade pip
その後VSCodeを開き、Python: Select Interpreterから.venvのPythonを選択します。
まとめ
VSCodeでpyenvを使う場合は、VSCodeの中でpyenvを直接操作するというより、pyenvで管理しているPython環境をVSCodeから利用すると考えると分かりやすいでしょう。
基本的な流れは、次のとおりです。
pyenvをインストール
↓
シェル設定を行う
↓
pyenv installでPythonをインストール
↓
pyenv localでプロジェクト用Pythonを指定
↓
python -m venv .venvで仮想環境を作成
↓
VSCodeでPython: Select Interpreterを実行
↓
.venvのPythonを選択
特に実務では、pyenvでPython本体のバージョンを管理し、venvでプロジェクトごとのパッケージ環境を分離し、VSCodeでは.venvをインタープリターとして選択する方法が分かりやすくおすすめです。
Windowsでは、本家pyenvをネイティブ環境で直接使うのではなく、WSL上で本家pyenvを使う方法や、Windows向けのpyenv-winを利用する方法を検討するとよいでしょう。
以上、VSCodeでpyenvを使う方法についてでした。
最後までお読みいただき、ありがとうございました。
