VS CodeでPython開発環境をvenvで構築する方法｜仮想環境の作り方から設定まで

python

Python開発を始めたばかりの人から、よくこんな質問をいただきます。

「複数のPythonプロジェクトを進めているけど、ライブラリのバージョンがぶつかって困っている」
「新しいプロジェクトを始めるとき、既存の環境を壊したくない」
「VS CodeでPythonの仮想環境をうまく使えない」

これらの問題を解決するカギが、仮想環境（venv）です。

仮想環境を使うことで、プロジェクトごとに独立したPython環境を作り、依存関係の問題を避けることができます。

この記事では、VS CodeでPythonの仮想環境を構築し、効率的に開発を進める方法を初心者にもわかりやすく解説します。

スポンサーリンク

仮想環境（venv）とは？基本概念

仮想環境の必要性

システム環境での問題

Pythonをシステム全体にインストールした場合、以下のような問題が発生します：

ライブラリバージョンの競合

# プロジェクトA: Django 3.2が必要
pip install Django==3.2

# プロジェクトB: Django 4.0が必要
pip install Django==4.0  # ← プロジェクトAが動かなくなる

依存関係の複雑化

# 異なるプロジェクトで同じライブラリの異なるバージョンが必要
プロジェクトA: requests==2.25.1, numpy==1.20.0
プロジェクトB: requests==2.28.0, numpy==1.21.0

システムの汚染

  • 不要なパッケージがシステム全体に残る
  • アンインストールの際に依存関係が複雑になる
  • システムPythonに影響を与えるリスク

仮想環境のメリット

プロジェクト独立性

システム全体
├── Python 3.9 (システム)
├── プロジェクトA/
│   └── venv/ (Django 3.2, requests 2.25.1)
├── プロジェクトB/
│   └── venv/ (Django 4.0, requests 2.28.0)
└── プロジェクトC/
    └── venv/ (Flask 2.0, SQLAlchemy 1.4)

主なメリット

  • バージョン競合の回避: プロジェクトごとに異なるバージョンを使用可能
  • クリーンな環境: 必要なパッケージのみをインストール
  • 再現可能性: requirements.txtで環境を再現可能
  • 実験の安全性: 新しいライブラリを試しても他に影響しない

venvとその他の仮想環境ツール

主要な仮想環境ツール比較

venv（標準ライブラリ）

  • Python 3.3以降に標準搭載
  • 軽量でシンプル
  • 基本的な仮想環境機能を提供

virtualenv

  • venvの前身
  • Python 2.7でも使用可能
  • より多くの機能を提供

conda

  • Anaconda/Minicondaで提供
  • パッケージ管理機能も含む
  • データサイエンス分野で人気

pipenv

  • pip + virtualenvの統合ツール
  • Pipfile/Pipfile.lockでの管理
  • 依存関係の解決が強力

この記事では、標準ライブラリで軽量なvenvを使用します。

事前準備とインストール

Pythonのインストール確認

インストール状況の確認

# Pythonのバージョン確認
python --version
# または
python3 --version

# pipのバージョン確認
pip --version
# または
pip3 --version

Pythonのインストール（まだインストールしていない場合）

Windows:

  1. Python公式サイトからダウンロード
  2. インストール時に「Add Python to PATH」にチェック
  3. 「Install Now」をクリック

macOS:

# Homebrewを使用（推奨）
brew install python

# 公式インストーラーを使用する場合は公式サイトからダウンロード

Linux (Ubuntu/Debian):

# システムのパッケージマネージャーを使用
sudo apt update
sudo apt install python3 python3-pip python3-venv

インストール後の確認

# Python REPL起動テスト
python
>>> print("Hello, Python!")
Hello, Python!
>>> exit()

# pip動作テスト
pip list

VS Codeのセットアップ

VS Code本体のインストール

  1. VS Code公式サイトからダウンロード
  2. お使いのOSに応じたインストーラーを実行
  3. 基本設定のまま進めてOK

必須拡張機能のインストール

Python拡張機能（Microsoft製）

  1. VS Codeを起動
  2. 拡張機能ビュー（Ctrl + Shift + X）を開く
  3. 「Python」で検索
  4. 「Python」（発行者: Microsoft）をインストール

その他の推奨拡張機能

  • Pylance: 高度な型チェックと補完
  • Python Docstring Generator: ドキュメント自動生成
  • GitLens: Git統合機能の強化

venv仮想環境の作成手順

プロジェクトフォルダの準備

基本的なプロジェクト構造

# プロジェクトフォルダの作成
mkdir my_python_project
cd my_python_project

# 基本的なファイル構造を作成
mkdir src tests docs
touch README.md requirements.txt .gitignore

.gitignoreファイルの設定

# 仮想環境フォルダを除外
venv/
env/
.venv/

# Python関連
__pycache__/
*.py[cod]
*$py.class
*.so
.Python
build/
develop-eggs/
dist/
downloads/
eggs/
.eggs/
lib/
lib64/
parts/
sdist/
var/
wheels/
*.egg-info/
.installed.cfg
*.egg

# IDE関連
.vscode/settings.json
.idea/

# OS関連
.DS_Store
Thumbs.db

仮想環境の作成

venvコマンドでの作成

# プロジェクトルートで実行
python -m venv venv

# 仮想環境名を変更したい場合
python -m venv my_project_env

# Python 3.9を明示的に指定（複数バージョンがある場合）
python3.9 -m venv venv

作成後のフォルダ構造

my_python_project/
├── venv/                   # 仮想環境フォルダ
│   ├── bin/               # (Linux/macOS) 実行ファイル
│   ├── Scripts/           # (Windows) 実行ファイル
│   ├── lib/               # インストールされたパッケージ
│   ├── include/           # ヘッダーファイル
│   └── pyvenv.cfg         # 仮想環境設定
├── src/                   # ソースコード
├── tests/                 # テストコード
├── README.md
├── requirements.txt
└── .gitignore

仮想環境の有効化

プラットフォーム別の有効化方法

Windows (Command Prompt):

.\venv\Scripts\activate

Windows (PowerShell):

.\venv\Scripts\Activate.ps1

# 実行ポリシーエラーが出る場合
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
.\venv\Scripts\Activate.ps1

macOS/Linux:

source venv/bin/activate

有効化の確認

# プロンプトに(venv)が表示されることを確認
(venv) $ python --version

# 仮想環境のPythonパスを確認
(venv) $ which python
/path/to/my_python_project/venv/bin/python

# インストール済みパッケージの確認
(venv) $ pip list
Package    Version
---------- -------
pip        21.3.1
setuptools 58.3.0

仮想環境の無効化

# 仮想環境を無効化
deactivate

# プロンプトから(venv)が消えることを確認
$ python --version

VS Codeでの仮想環境設定

Pythonインタープリターの選択

自動認識による選択

  1. VS Codeでプロジェクトフォルダを開く
    • 「ファイル」→「フォルダーを開く」
    • プロジェクトルートフォルダを選択
  2. Python拡張機能が仮想環境を自動検出
    • 通常、venvフォルダがあると自動で検出される
    • 右下に「Select Python Interpreter」の通知が表示される場合がある
  3. インタープリターの確認
    • VS Code左下のステータスバーにPythonバージョンが表示される
    • 正しい仮想環境が選択されているか確認

手動での選択方法

方法1: ステータスバーから

  1. VS Code左下の「Python 3.x.x」表示をクリック
  2. インタープリター一覧から仮想環境のPythonを選択
  3. ./venv/bin/python（Windows: .\venv\Scripts\python.exe）を選択

方法2: コマンドパレットから

  1. Ctrl + Shift + Pでコマンドパレットを開く
  2. 「Python: Select Interpreter」と入力
  3. 仮想環境のPythonを選択

方法3: settings.jsonで指定

{
  "python.defaultInterpreterPath": "./venv/bin/python"
}

VS Code統合ターミナルの設定

自動的な仮想環境有効化

// .vscode/settings.json
{
  "python.terminal.activateEnvironment": true,
  "python.defaultInterpreterPath": "./venv/bin/python"
}

この設定により、新しいターミナルを開くたびに自動で仮想環境が有効化されます。

ターミナルでの確認

# 新しいターミナルを開く (Ctrl + `)
# 自動的に(venv)が表示されることを確認
(venv) $ python --version
Python 3.9.x

(venv) $ which python
/path/to/project/venv/bin/python

デバッグ設定の構成

launch.jsonの作成

// .vscode/launch.json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Python: Current File",
      "type": "python",
      "request": "launch",
      "program": "${file}",
      "console": "integratedTerminal",
      "cwd": "${workspaceFolder}",
      "python": "${workspaceFolder}/venv/bin/python"
    },
    {
      "name": "Python: Module",
      "type": "python",
      "request": "launch",
      "module": "src.main",
      "console": "integratedTerminal",
      "cwd": "${workspaceFolder}",
      "python": "${workspaceFolder}/venv/bin/python"
    }
  ]
}

パッケージ管理とrequirements.txt

パッケージのインストール

基本的なパッケージインストール

# 仮想環境を有効化してからインストール
(venv) $ pip install requests
(venv) $ pip install pandas numpy matplotlib
(venv) $ pip install django==4.1.0  # バージョン指定

# 開発用パッケージのインストール
(venv) $ pip install pytest black flake8 mypy

パッケージ情報の確認

# インストール済みパッケージの一覧
(venv) $ pip list

# 特定パッケージの詳細情報
(venv) $ pip show requests

# 依存関係の表示
(venv) $ pip show --verbose requests

requirements.txtの作成と管理

requirements.txtの生成

# 現在の環境からrequirements.txtを生成
(venv) $ pip freeze > requirements.txt

requirements.txtの例

# requirements.txt
Django==4.1.0
requests==2.28.1
pandas==1.5.0
numpy==1.23.0
matplotlib==3.6.0

# 開発用ライブラリ（別ファイルに分ける場合）
# pytest==7.1.2
# black==22.8.0
# flake8==5.0.4

開発用ライブラリの分離

# 本番用
pip freeze | grep -v "pytest\|black\|flake8" > requirements.txt

# 開発用
echo "pytest==7.1.2" > requirements-dev.txt
echo "black==22.8.0" >> requirements-dev.txt
echo "flake8==5.0.4" >> requirements-dev.txt

requirements.txtからのインストール

# 新しい環境での復元
(venv) $ pip install -r requirements.txt

# 開発用ライブラリも含めてインストール
(venv) $ pip install -r requirements.txt -r requirements-dev.txt

開発効率を上げる設定

VS Code設定の最適化

プロジェクト固有設定

// .vscode/settings.json
{
  // Python基本設定
  "python.defaultInterpreterPath": "./venv/bin/python",
  "python.terminal.activateEnvironment": true,
  
  // フォーマット設定
  "[python]": {
    "editor.formatOnSave": true,
    "editor.defaultFormatter": "ms-python.black-formatter",
    "editor.codeActionsOnSave": {
      "source.organizeImports": true
    }
  },
  
  // リント設定
  "python.linting.enabled": true,
  "python.linting.flake8Enabled": true,
  "python.linting.pylintEnabled": false,
  
  // テスト設定
  "python.testing.pytestEnabled": true,
  "python.testing.unittestEnabled": false,
  "python.testing.pytestArgs": ["tests"],
  
  // その他
  "python.analysis.typeCheckingMode": "basic",
  "files.exclude": {
    "**/__pycache__": true,
    "**/*.pyc": true
  }
}

推奨拡張機能の指定

// .vscode/extensions.json
{
  "recommendations": [
    "ms-python.python",
    "ms-python.pylance",
    "ms-python.black-formatter",
    "ms-toolsai.jupyter",
    "njpwerner.autodocstring"
  ]
}

自動フォーマット設定

Black（コードフォーマッタ）の設定

# Blackのインストール
(venv) $ pip install black

# 手動でフォーマット
(venv) $ black src/

# 設定ファイル作成（任意）
# pyproject.toml

[tool.black]
line-length = 88 target-version = ['py39'] 
include = '\.pyi?$' 
extend-exclude = ''' ( migrations/ | venv/ ) '''

isort（インポート文整理）の設定

# isortのインストール
(venv) $ pip install isort

# 手動で整理
(venv) $ isort src/

# 設定ファイル
# .isort.cfg

[settings]
profile = black 
multi_line_output = 3 
line_length = 88 
include_trailing_comma = True

リント設定

Flake8（構文チェック）の設定

# Flake8のインストール
(venv) $ pip install flake8

# 設定ファイル
# .flake8

[flake8]
max-line-length = 88 
extend-ignore = E203, W503 
exclude = venv/, migrations/, __pycache__/

VS Codeでのリント設定

{
  "python.linting.enabled": true,
  "python.linting.flake8Enabled": true,
  "python.linting.flake8Args": ["--max-line-length=88"],
  "python.linting.lintOnSave": true
}

プロジェクト構造のベストプラクティス

推奨フォルダ構造

my_python_project/
├── .vscode/                # VS Code設定
│   ├── settings.json
│   ├── launch.json
│   └── extensions.json
├── venv/                   # 仮想環境（.gitignoreに含める）
├── src/                    # メインのソースコード
│   ├── __init__.py
│   ├── main.py
│   ├── models/
│   │   ├── __init__.py
│   │   └── user.py
│   └── utils/
│       ├── __init__.py
│       └── helpers.py
├── tests/                  # テストコード
│   ├── __init__.py
│   ├── test_main.py
│   └── test_models/
│       ├── __init__.py
│       └── test_user.py
├── docs/                   # ドキュメント
├── scripts/                # 実行スクリプト
├── .gitignore
├── README.md
├── requirements.txt
├── requirements-dev.txt
├── pyproject.toml         # プロジェクト設定
└── setup.py               # パッケージ設定（必要に応じて）

プロジェクト初期化スクリプト

自動化スクリプトの作成

#!/bin/bash
# init_project.sh

PROJECT_NAME=$1

if [ -z "$PROJECT_NAME" ]; then
    echo "Usage: $0 <project_name>"
    exit 1
fi

# プロジェクトフォルダ作成
mkdir $PROJECT_NAME
cd $PROJECT_NAME

# 基本構造作成
mkdir -p src tests docs scripts .vscode

# 仮想環境作成
python -m venv venv

# 基本ファイル作成
touch README.md requirements.txt requirements-dev.txt .gitignore
touch src/__init__.py src/main.py
touch tests/__init__.py tests/test_main.py

# .gitignore作成
cat > .gitignore << EOF
venv/
__pycache__/
*.py[cod]
*$py.class
.vscode/settings.json
.env
.DS_Store
EOF

# VS Code設定
cat > .vscode/settings.json << EOF
{
  "python.defaultInterpreterPath": "./venv/bin/python",
  "python.terminal.activateEnvironment": true,
  "[python]": {
    "editor.formatOnSave": true,
    "editor.defaultFormatter": "ms-python.black-formatter"
  }
}
EOF

echo "Project $PROJECT_NAME initialized successfully!"
echo "Next steps:"
echo "1. cd $PROJECT_NAME"
echo "2. source venv/bin/activate"
echo "3. pip install -r requirements-dev.txt"
echo "4. code ."

よくある問題と解決方法

仮想環境の問題

問題1: venvが作成できない

症状:

$ python -m venv venv
Error: Command '['/path/to/venv/bin/python', '-Im', 'ensurepip']' returned non-zero exit status 1

解決方法:

# Python venvモジュールの確認
python -c "import venv"

# Ubuntu/Debianの場合
sudo apt install python3-venv

# pipの手動インストール
python -m ensurepip --upgrade

問題2: 仮想環境の有効化に失敗

Windows PowerShell実行ポリシーエラー:

# 実行ポリシーの確認
Get-ExecutionPolicy

# ユーザー用実行ポリシーの変更
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# 仮想環境の有効化
.\venv\Scripts\Activate.ps1

macOS/Linux権限エラー:

# 実行権限の付与
chmod +x venv/bin/activate

# 有効化
source venv/bin/activate

VS Code認識の問題

問題3: VS Codeが仮想環境を認識しない

確認事項:

  1. venvフォルダがプロジェクトルートにあるか
  2. Python拡張機能がインストールされているか
  3. VS Codeでプロジェクトルートフォルダを開いているか

解決方法:

# VS Codeの再起動
# コマンドパレット → "Developer: Reload Window"

# 手動でインタープリター選択
# Ctrl + Shift + P → "Python: Select Interpreter"

問題4: デバッグが仮想環境を使わない

launch.jsonの確認:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Python: Current File",
      "type": "python",
      "request": "launch",
      "program": "${file}",
      "console": "integratedTerminal",
      "python": "${workspaceFolder}/venv/bin/python"  // 重要
    }
  ]
}

パッケージ管理の問題

問題5: パッケージインストールエラー

ネットワーク関連エラー:

# プロキシ環境での設定
pip install --proxy http://proxy.company.com:8080 package_name

# 信頼できるホストの追加
pip install --trusted-host pypi.org --trusted-host pypi.python.org package_name

権限エラー:

# 仮想環境が有効化されているか確認
echo $VIRTUAL_ENV  # パスが表示されるはず

# 仮想環境の再作成
deactivate
rm -rf venv
python -m venv venv
source venv/bin/activate

問題6: requirements.txtが正しく動作しない

バージョン競合の解決:

# 依存関係の確認
pip check

# 強制再インストール
pip install --force-reinstall -r requirements.txt

# キャッシュクリア
pip cache purge
pip install --no-cache-dir -r requirements.txt

高度な活用方法

複数Python環境の管理

pyenvとの組み合わせ

# pyenvで特定バージョンのPythonをインストール
pyenv install 3.9.16
pyenv install 3.11.0

# プロジェクトディレクトリでバージョン指定
cd my_project
pyenv local 3.9.16

# 指定バージョンでvenv作成
python -m venv venv

環境別の設定管理

# 開発環境
python -m venv venv-dev
source venv-dev/bin/activate
pip install -r requirements-dev.txt

# 本番環境シミュレーション
python -m venv venv-prod
source venv-prod/bin/activate
pip install -r requirements.txt

CI/CDとの連携

GitHub Actionsでの設定例

# .github/workflows/test.yml
name: Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: [3.8, 3.9, 3.10]

    steps:
    - uses: actions/checkout@v3
    
    - name: Set up Python ${{ matrix.python-version }}
      uses: actions/setup-python@v4
      with:
        python-version: ${{ matrix.python-version }}
    
    - name: Create virtual environment
      run: |
        python -m venv venv
        source venv/bin/activate
        pip install --upgrade pip
    
    - name: Install dependencies
      run: |
        source venv/bin/activate
        pip install -r requirements.txt
        pip install -r requirements-dev.txt
    
    - name: Run tests
      run: |
        source venv/bin/activate
        pytest tests/

Docker環境での活用

Dockerfile例

FROM python:3.9-slim

WORKDIR /app

# 仮想環境作成
RUN python -m venv venv
ENV PATH="/app/venv/bin:$PATH"

# 依存関係インストール
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# アプリケーションコピー
COPY src/ ./src/

CMD ["python", "src/main.py"]

まとめ

VS CodeでPythonの仮想環境（venv）を活用することで、効率的で安全な開発環境を構築できます。

重要なポイント

  • 仮想環境の作成: python -m venv venvで独立した環境を構築
  • VS Code連携: インタープリター選択で仮想環境を認識
  • パッケージ管理: requirements.txtで依存関係を明確化
  • 開発設定: settings.jsonで自動フォーマットとリント設定

効果的な活用方法

  • プロジェクト分離: 各プロジェクトで独立した環境を維持
  • チーム協力: 統一された開発環境で共同作業
  • 継続的改善: リント・フォーマットで コード品質向上
  • 問題解決: よくある問題への対処法を把握

Youtube

神話・歴史・伝承の解説チャンネル

スポンサーリンク

コメント

タイトルとURLをコピーしました