[NOTE] VS Codeで仮想環境を設定・自動認識させる方法

はじめに

VS CodeでPythonを開発する場合、プロジェクトごとに仮想環境（".venv"）を作成しておくと、ライブラリの競合や環境依存のトラブルを防ぎやすくなります。

本記事では、Windows環境を前提として、

• Pythonの確認
• 仮想環境の作成
• VS Codeへの認識
• 自動有効化
• "requirements.txt"の作成
• ".gitignore"の設定
• トラブルシューティング

までをまとめます。

---

1. 基本方針

おすすめは、

«1プロジェクト = 1仮想環境（".venv"）»

という構成です。

例えば複数のPythonプロジェクトを作る場合、

C:\Users\Public\Documents\ws
│
├─ image_manager
│ └─ .venv
│
├─ excel_automation
│ └─ .venv
│
└─ graphviz_tool
└─ .venv\

のように、それぞれ独立した仮想環境を持たせます。

メリット

• プロジェクトごとにライブラリを分離できる
• ライブラリのバージョン競合を防げる
• 他のプロジェクトに影響しない
• VS Codeで自動的に認識できる
• "requirements.txt"による環境再構築がしやすい

---

1. Pythonがインストールされているか確認

WindowsのPowerShellを開きます。

py --version

例えば、

Python 3.13.7

と表示されればOKです。

"python"ではなく"py"を使う理由

Windowsでは、

python --version

を実行すると、

Python was not found

となる場合があります。

一方、

py --version

が動く場合は、Python Launcherが利用できます。

そのため、仮想環境の作成では、

py -m venv .venv

を使用すると安定します。

---

1. プロジェクトフォルダを作成

例えば、

mkdir C:\Users\Public\Documents\ws\my_project
cd C:\Users\Public\Documents\ws\my_project

VS Codeで開く場合は、

code .

とします。

---

1. 仮想環境を作成

プロジェクトフォルダで、

py -m venv .venv

を実行します。

すると、

my_project
└─ .venv\

が作成されます。

".venv"には、このプロジェクト専用のPython環境が入ります。

---

1. 仮想環境を有効化

PowerShellの場合、

..venv\Scripts\Activate.ps1

を実行します。

成功すると、ターミナルの先頭に、

(.venv) PS C:\Users...\my_project>

のように、

(.venv)

が表示されます。

これで仮想環境が有効になっています。

---

1. VS CodeでPythonインタープリターを選択

VS Codeで、

Ctrl + Shift + P

を押します。

続いて、

Python: Select Interpreter

を選択します。

一覧から、

.venv\Scripts\python.exe

を選択します。

これで、このプロジェクトでは".venv"のPythonを使用するようになります。

---

1. VS Codeで自動認識させる

毎回Pythonインタープリターを選択するのが面倒な場合は、プロジェクト内に、

.vscode\settings.json

を作成します。

内容：

{
"python.defaultInterpreterPath": "${workspaceFolder}/.venv/Scripts/python.exe",
"python.terminal.activateEnvironment": true
}

"python.defaultInterpreterPath"

"python.defaultInterpreterPath": "${workspaceFolder}/.venv/Scripts/python.exe"

プロジェクトフォルダ内の、

.venv\Scripts\python.exe

をPythonインタープリターとして使用します。

"python.terminal.activateEnvironment"

"python.terminal.activateEnvironment": true

VS Codeのターミナルを起動したときに、仮想環境を自動的に有効化します。

---

1. 推奨するプロジェクト構成

最終的には、以下のような構成がおすすめです。

my_project/
│
├─ .venv/
│
├─ src/
│ └─ main.py
│
├─ requirements.txt
│
├─ .gitignore
│
└─ .vscode/
└─ settings.json

それぞれの役割は以下のとおりです。

ファイル・フォルダ| 役割
".venv"| プロジェクト専用の仮想環境
"src"| Pythonプログラム
"main.py"| メインプログラム
"requirements.txt"| 使用するライブラリ一覧
".gitignore"| Gitなどから除外するファイル
".vscode/settings.json"| VS Codeの設定

---

1. 仮想環境が正しく認識されているか確認

VS Codeのターミナルで、

python -c "import sys; print(sys.executable)"

を実行します。

理想的な結果は、

C:\Users\Public\Documents\ws\my_project.venv\Scripts\python.exe

です。

つまり、

プロジェクト
↓
.venv
↓
Scripts
↓
python.exe

となっていればOKです。

---

1. Pythonのバージョン確認

python --version

例：

Python 3.13.7

---

1. pipの確認

python -m pip --version

ライブラリをインストールするときも、

python -m pip install pandas

のように、

python -m pip

を使用するのがおすすめです。

これにより、現在使用しているPython環境に対応したpipを確実に利用できます。

---

1. ライブラリをインストール

例えば、

python -m pip install pandas

python -m pip install openpyxl

python -m pip install pillow

複数まとめてインストールすることもできます。

python -m pip install pandas openpyxl pillow

---

1. requirements.txtを作成

インストールしたライブラリを保存するには、

python -m pip freeze > requirements.txt

を実行します。

すると、

requirements.txt

に現在の環境にインストールされているパッケージが記録されます。

別のPCや新しい仮想環境で復元するときは、

python -m pip install -r requirements.txt

でインストールできます。

---

1. .gitignoreを設定

".venv"はプロジェクトごとに作り直せるため、Gitなどに保存する必要はありません。

".gitignore"を作成し、

.venv/
pycache/
*.pyc
.env

としておきます。

---

1. よく使うコマンド一覧

操作| コマンド
Python確認| "py --version"
仮想環境作成| "py -m venv .venv"
仮想環境有効化| "..venv\Scripts\Activate.ps1"
仮想環境確認| "python -c "import sys; print(sys.executable)""
Python確認| "python --version"
pip確認| "python -m pip --version"
ライブラリインストール| "python -m pip install パッケージ名"
requirements作成| "python -m pip freeze > requirements.txt"
requirementsから復元| "python -m pip install -r requirements.txt"
仮想環境終了| "deactivate"

---

1. トラブルシューティング

16.1 「Python was not found」と表示される

まず、

py --version

を確認します。

"py"が動く場合は、

py -m venv .venv

で仮想環境を作成します。

---

16.2 VS Codeが".venv"を認識しない

以下を確認します。

".venv"が存在するか

my_project/
└─ .venv/

Pythonインタープリターを確認

Ctrl + Shift + P
↓
Python: Select Interpreter
↓
.venv\Scripts\python.exe

settings.jsonを確認

{
"python.defaultInterpreterPath": "${workspaceFolder}/.venv/Scripts/python.exe",
"python.terminal.activateEnvironment": true
}

それでも認識しない場合は、VS Codeを再起動するか、

Ctrl + Shift + P
↓
Developer: Reload Window

を実行します。

---

1. PowerShellでActivateできない場合

以下のようなエラーが出る場合があります。

running scripts is disabled on this system

PowerShellの実行ポリシーが原因です。

ユーザー単位で変更する場合：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

確認されたら、

Y

を入力します。

その後、

..venv\Scripts\Activate.ps1

を再実行します。

---

1. 現在どのPythonを使っているか確認する

最も重要な確認方法です。

python -c "import sys; print(sys.executable)"

結果が、

...\my_project.venv\Scripts\python.exe

になっていれば、そのプロジェクトの仮想環境を使用しています。

さらに、

where.exe python

でもPythonの場所を確認できます。

---

1. 新しいPythonプロジェクトを作るときの基本手順

今後は基本的に、以下の流れに統一すると管理しやすくなります。

① プロジェクトフォルダ作成
↓
② VS Codeで開く
↓
③ py -m venv .venv
↓
④ .vscode/settings.json作成
↓
⑤ Python: Select Interpreter
↓
⑥ .venvを選択
↓
⑦ Pythonの実行パスを確認
↓
⑧ ライブラリをインストール
↓
⑨ requirements.txtを保存

---

1. 最終的に覚えておきたい設定

".vscode/settings.json"

{
"python.defaultInterpreterPath": "${workspaceFolder}/.venv/Scripts/python.exe",
"python.terminal.activateEnvironment": true
}

".gitignore"

.venv/
pycache/
*.pyc
.env

仮想環境作成

py -m venv .venv

仮想環境有効化

..venv\Scripts\Activate.ps1

Pythonの実体を確認

python -c "import sys; print(sys.executable)"

---

1. 重要ポイント

VS CodeでPythonを安定して使用するうえで最も重要なのは、

«「今、どのPythonを使っているのか」を確認すること»

です。

以下を実行して、

python -c "import sys; print(sys.executable)"

プロジェクト.venv\Scripts\python.exe

となっていればOKです。

この構成にしておけば、プロジェクトごとにPython環境を分離でき、ライブラリの競合や「VS Codeでは動くのに別のターミナルでは動かない」といったトラブルを減らすことができます。

---

まとめ

Windows + VS CodeでPythonを開発する場合は、

1プロジェクト
↓
専用の.venv
↓
VS Codeが.venvを自動認識
↓
python -m pipでライブラリ管理
↓
requirements.txtで環境を保存

という構成にしておくのがおすすめです。

特に、

py -m venv .venv

と

"python.defaultInterpreterPath": "${workspaceFolder}/.venv/Scripts/python.exe"

を基本セットとして覚えておくと、VS CodeでのPython環境構築がかなり楽になります。