【2025年版】VSCode Python開発はPylanceで決まり

要約

Pylanceは、MicrosoftがVSCode向けに開発した高機能なPython言語サーバーである。型チェックだけでなく、コード補完、自動インポート、シンタックスハイライトなど、Python開発に必要な機能を包括的に提供する。内部でPyrightを使用しているため、別途型チェッカーをインストールする必要がなく、VSCodeとの統合も優れている。本記事では、Pylanceのインストールから詳細な設定方法、トラブルシューティングまで実践的に解説する。

対象読者: Python初心者〜中級者、VSCodeでPython開発を行う開発者

検証環境: VSCode最新版、Python 3.8以降（2025年1月時点）

この記事を読むことで得られるメリット

この記事を読むことで以下のことが分かる:

VSCodeでPython開発に最適なリンター（Pylance）の選び方
Pylance、Pyright、mypyの違いと使い分け
リンターがもたらすコード品質向上の具体的なメリット
実務で使えるPylanceのおすすめ設定と設定方法
プロジェクト別の設定パターン（レガシー、新規、大規模、学習用、Django/Flask）
CI/CD連携の設定例（GitHub Actions、GitLab CI、pre-commit）
チーム開発での運用ガイドと設定統一の方法
よくあるエラーとトラブルシューティング方法

この記事を読むのにかかる時間

約15分

環境

MacOS Apple M4 Max Sequoia 15.1
Visual Studio Code 1.85以降
Python 3.8以降

リンターとは

リンター（Linter）とは、Pythonのソースコードを静的に解析し、以下の問題を検出するツールである。

検出できる問題:

構文エラー
型の不一致
未使用の変数やインポート
コーディング規約違反（PEP 8など）
潜在的なバグやサスペクトな構造

リンターのメリット:

コードの品質向上
バグの早期発見
チーム開発でのコード統一
リファクタリングの安全性向上
実行前のエラー検出

リンターを活用することで、実行時エラーを事前に防ぎ、保守性の高いコードを書くことができる。

VSCodeで使用すべきPythonリンター

VSCodeでPython開発を行う際、リンターについて調べると以下の選択肢がよく出てくる。

主なリンターの選択肢:

Pylance - Microsoft製の包括的な言語サーバー
Pyright - Microsoft製の型チェッカー
mypy - サードパーティ製の型チェッカー
Flake8 - PEP 8準拠チェッカー
Pylint - 総合的なコード品質チェッカー

結論: 2025年現在、Pylanceを使うべき理由

包括的な機能: 型チェック+コード補完+自動インポート+その他多数の機能
VSCodeとの統合: VSCode公式のPython拡張機能に含まれている
高速: 大規模プロジェクトでも高速に動作
Pyrightを内蔵: 別途型チェッカーをインストール不要
継続的な開発: Microsoftによる積極的な開発とサポート

Pylance vs Pyright vs mypy - 比較表

機能	Pylance	Pyright	mypy
型チェック	✅	✅	✅
コード補完	✅	❌	❌
自動インポート	✅	❌	❌
シンタックスハイライト	✅	❌	❌
ドキュメントホバー	✅	❌	❌
シグネチャヘルプ	✅	❌	❌
VSCode統合	✅ 公式	△ 可能	△ 可能
インストール	拡張機能	npm	pip
開発元	Microsoft	Microsoft	Python
パフォーマンス	高速	高速	中速

推奨される使い分け:

VSCodeユーザー: Pylance（一択）
他のエディタ: PyrightまたはMicrosoft製品を好む場合はPyright、Pythonコミュニティ標準を好む場合はmypy
CI/CD: PyrightまたはMypy（コマンドラインで実行）

Pylanceの特徴

1. Microsoft製の公式言語サーバー

PylanceはMicrosoftが開発しているVSCode公式のPython言語サーバーである。VSCodeのPython拡張機能に含まれており、追加のインストールは不要である。

2. Pyrightベースの型チェック

Pylanceは内部でPyrightを型チェックエンジンとして使用している。つまり、Pyrightの高速で正確な型チェック機能をそのまま利用できる。Pyrightを別途pipでインストールする必要はない。

3. 包括的な開発支援機能

型チェックだけでなく、以下の機能を統合的に提供する:

インテリセンス（コード補完）:

文脈に応じた正確な補完候補
型情報に基づく補完
ドキュメント文字列の表示

自動インポート:

未インポートのモジュールを自動検出
インポート文の自動追加
整理されたインポート順序

コードナビゲーション:

定義へジャンプ（Go to Definition）
参照の検索（Find All References）
シンボルの名前変更（Rename Symbol）

型ヒント表示:

インラインで型情報を表示
関数の返り値型を自動推論
変数の型をホバーで確認

4. 3つのチェックレベル

Pylanceは、プロジェクトの規模や開発フェーズに応じて型チェックの厳格さを調整できる。

レベル	説明	推奨用途
`off`	型チェックを行わない	レガシーコード、型ヒントなしのプロジェクト
`basic`	基本的な型チェック	一般的な開発（推奨）
`strict`	最も厳格な型チェック	高品質が求められるプロジェクト、新規開発

インストール方法

ステップ1: Python拡張機能のインストール

VSCodeのExtensionsから以下の拡張機能をインストールする。

拡張機能名: Python 公開元: Microsoft マーケットプレイスURL: https://marketplace.visualstudio.com/items?itemName=ms-python.python

インストール手順:

VSCodeを開く
サイドバーの拡張機能アイコンをクリック（またはCmd+Shift+X / Ctrl+Shift+X）
検索ボックスに「Python」と入力
Microsoft製の「Python」拡張機能を選択
「Install」をクリック

ステップ2: Pylanceが有効になっているか確認

Python拡張機能をインストールすると、Pylanceは自動的に有効になる。確認方法は以下の通り。

VSCodeでPythonファイル（.py）を開く
ステータスバー（下部）に「Pylance」と表示されていることを確認
または、設定（settings.json）で以下を確認:

{
  "python.languageServer": "Pylance"
}

基本設定

Pylanceをインストールしただけでも十分に機能するが、settings.jsonで設定をカスタマイズすることで、より快適な開発環境を構築できる。

settings.jsonの開き方

VSCodeでCmd+Shift+P（Windows/Linux: Ctrl+Shift+P）を押す
「Preferences: Open Settings (JSON)」と入力
settings.jsonが開く

最小限の推奨設定

{
  // Pylanceを言語サーバーとして使用
  "python.languageServer": "Pylance",

  // 型チェックレベル（基本的なチェックを有効化）
  "python.analysis.typeCheckingMode": "basic"
}

この2行だけで、Pylanceの基本的な機能が有効になる。

完全版settings.json例

実務で使える、すべての推奨設定をまとめたsettings.jsonの例である。

{
  // ===== Pylance基本設定 =====
  "python.languageServer": "Pylance",
  "python.analysis.typeCheckingMode": "basic",

  // ===== 未使用項目の検出 =====
  "python.analysis.diagnosticSeverityOverrides": {
    "reportUnusedImport": "error",
    "reportUnusedClass": "error",
    "reportUnusedFunction": "error",
    "reportUnusedVariable": "warning",
    "reportMissingImports": "error",
    "reportMissingTypeStubs": "warning"
  },

  // ===== コード補完設定 =====
  "python.analysis.completeFunctionParens": true,
  "python.analysis.autoImportCompletions": true,

  // ===== 型ヒント表示 =====
  "python.analysis.inlayHints.variableTypes": true,
  "python.analysis.inlayHints.functionReturnTypes": true,
  "python.analysis.inlayHints.callArgumentNames": "partial",
  "python.analysis.inlayHints.pytestParameters": true,

  // ===== 診断設定 =====
  "python.analysis.diagnosticMode": "workspace",
  "python.analysis.autoSearchPaths": true,

  // ===== 保存時の自動処理 =====
  "editor.codeActionsOnSave": {
    "source.organizeImports": "explicit"
  },
  "editor.formatOnSave": true,

  // ===== その他の推奨設定 =====
  "python.analysis.useLibraryCodeForTypes": true,
  "python.analysis.indexing": true
}

カスタマイズのポイント:

typeCheckingModeは、慣れてきたら"strict"に変更
reportUnusedVariableは、開発中は"warning"、本番前は"error"に
プロジェクトの規模が大きい場合はdiagnosticModeを"openFilesOnly"に変更してパフォーマンス向上

プロジェクト別の設定パターン集

プロジェクトの特性や開発フェーズに応じて、最適な設定パターンを紹介する。

パターン1: レガシープロジェクト向け設定

既存のコードベースで型ヒントが少なく、徐々にコード品質を向上させたい場合の設定。

{
  "python.languageServer": "Pylance",

  // 型チェックは緩めに設定
  "python.analysis.typeCheckingMode": "off",

  // 開いているファイルのみチェック（パフォーマンス優先）
  "python.analysis.diagnosticMode": "openFilesOnly",

  // 未使用インポートのみエラーとして検出
  "python.analysis.diagnosticSeverityOverrides": {
    "reportUnusedImport": "error",
    "reportUnusedVariable": "none",
    "reportMissingTypeStubs": "none",
    "reportMissingImports": "warning"
  },

  // 基本的なコード補完機能のみ有効化
  "python.analysis.autoImportCompletions": true,
  "python.analysis.completeFunctionParens": false,

  // 型ヒント表示はオフ（コードの見た目を変えない）
  "python.analysis.inlayHints.variableTypes": false,
  "python.analysis.inlayHints.functionReturnTypes": false
}

適用場面:

長年運用されているプロジェクト
型ヒントがほとんどないコードベース
まずは基本的な品質向上から始めたい場合

パターン2: 新規プロジェクト向け設定（strict モード）

新規プロジェクトで、最初から高い型安全性を確保したい場合の設定。

{
  "python.languageServer": "Pylance",

  // 最も厳格な型チェック
  "python.analysis.typeCheckingMode": "strict",

  // ワークスペース全体をチェック
  "python.analysis.diagnosticMode": "workspace",

  // すべての問題をエラーとして扱う
  "python.analysis.diagnosticSeverityOverrides": {
    "reportUnusedImport": "error",
    "reportUnusedClass": "error",
    "reportUnusedFunction": "error",
    "reportUnusedVariable": "error",
    "reportMissingImports": "error",
    "reportMissingTypeStubs": "error",
    "reportGeneralTypeIssues": "error",
    "reportOptionalMemberAccess": "error",
    "reportOptionalSubscript": "error",
    "reportPrivateImportUsage": "error"
  },

  // フル機能を有効化
  "python.analysis.completeFunctionParens": true,
  "python.analysis.autoImportCompletions": true,
  "python.analysis.inlayHints.variableTypes": true,
  "python.analysis.inlayHints.functionReturnTypes": true,
  "python.analysis.inlayHints.callArgumentNames": "all",

  // 保存時の自動フォーマットと整理
  "editor.codeActionsOnSave": {
    "source.organizeImports": "explicit",
    "source.fixAll": "explicit"
  },
  "editor.formatOnSave": true,
  "[python]": {
    "editor.defaultFormatter": "ms-python.black-formatter"
  }
}

適用場面:

ゼロから始める新規プロジェクト
高品質なコードベースを維持したい場合
チーム全体で型安全性を重視する方針の場合

パターン3: 大規模プロジェクト向け設定（パフォーマンス重視）

数千〜数万行のコードベースで、パフォーマンスを優先したい場合の設定。

{
  "python.languageServer": "Pylance",
  "python.analysis.typeCheckingMode": "basic",

  // 開いているファイルのみチェック
  "python.analysis.diagnosticMode": "openFilesOnly",

  // インデックス作成を無効化（起動高速化）
  "python.analysis.indexing": false,

  // 除外ディレクトリを明示的に指定
  "python.analysis.exclude": [
    "**/node_modules",
    "**/.venv",
    "**/venv",
    "**/__pycache__",
    "**/site-packages",
    "**/migrations",  // Djangoのマイグレーションファイル
    "**/tests"  // テストコードは除外（必要に応じて）
  ],

  // 型スタブの自動検索を無効化
  "python.analysis.autoSearchPaths": false,

  // ライブラリコードの型情報は使わない（高速化）
  "python.analysis.useLibraryCodeForTypes": false,

  // 必要最小限の診断のみ
  "python.analysis.diagnosticSeverityOverrides": {
    "reportUnusedImport": "warning",
    "reportMissingImports": "error"
  }
}

適用場面:

10,000行以上の大規模プロジェクト
マシンスペックが低い環境
開発速度を優先したい場合

パターン4: 学習・個人開発向け設定（バランス型）

学習目的や個人開発で、適度なサポートを受けつつ柔軟に開発したい場合の設定。

{
  "python.languageServer": "Pylance",
  "python.analysis.typeCheckingMode": "basic",
  "python.analysis.diagnosticMode": "workspace",

  // 警告として表示（エラーにはしない）
  "python.analysis.diagnosticSeverityOverrides": {
    "reportUnusedImport": "warning",
    "reportUnusedVariable": "warning",
    "reportMissingImports": "error"
  },

  // 学習に役立つ機能を有効化
  "python.analysis.completeFunctionParens": true,
  "python.analysis.autoImportCompletions": true,

  // 型ヒントは関数の返り値のみ表示
  "python.analysis.inlayHints.variableTypes": false,
  "python.analysis.inlayHints.functionReturnTypes": true,

  // ドキュメント文字列の表示を有効化
  "python.analysis.autoFormatStrings": true,

  // 保存時にインポートを整理
  "editor.codeActionsOnSave": {
    "source.organizeImports": "explicit"
  }
}

適用場面:

Pythonを学習中の初心者
個人の趣味プロジェクト
厳格すぎない環境で開発したい場合

パターン5: Django/Flask プロジェクト向け設定

Webフレームワークを使用するプロジェクトの設定例。

{
  "python.languageServer": "Pylance",
  "python.analysis.typeCheckingMode": "basic",

  // Djangoの動的な属性に対応
  "python.analysis.diagnosticSeverityOverrides": {
    "reportGeneralTypeIssues": "none",  // Django ORM の動的属性対応
    "reportOptionalMemberAccess": "warning",
    "reportUnusedImport": "error"
  },

  // 追加のインポートパスを指定
  "python.analysis.extraPaths": [
    "${workspaceFolder}/apps",  // Djangoのappsディレクトリ
    "${workspaceFolder}/lib"
  ],

  // テンプレートやマイグレーションファイルを除外
  "python.analysis.exclude": [
    "**/templates",
    "**/migrations",
    "**/static"
  ],

  // 自動インポートとコード補完
  "python.analysis.autoImportCompletions": true,
  "python.analysis.completeFunctionParens": true
}

適用場面:

Django、Flaskなどのフレームワーク使用時
ORMの動的属性が多い場合

CI/CD連携の設定例

Pylanceは開発環境だけでなく、CI/CDパイプラインでもコード品質チェックに活用できる。

GitHub Actionsでの設定例

GitHubのリポジトリにプッシュされたコードを自動的に型チェックする設定。

.github/workflows/python-lint.yml:

name: Python Lint and Type Check

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main, develop ]

jobs:
  lint:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v3

    - name: Set up Python
      uses: actions/setup-python@v4
      with:
        python-version: '3.11'

    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install pyright  # Pylanceの型チェックエンジン
        pip install -r requirements.txt

    - name: Run Pyright type check
      run: |
        pyright --project .

    - name: Run additional linters (optional)
      run: |
        pip install flake8 black
        flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
        black --check .

pyrightconfig.json（プロジェクトルートに配置）:

{
  "include": [
    "src",
    "app"
  ],
  "exclude": [
    "**/node_modules",
    "**/__pycache__",
    "**/migrations"
  ],
  "typeCheckingMode": "basic",
  "reportMissingImports": true,
  "reportMissingTypeStubs": false,
  "pythonVersion": "3.11",
  "pythonPlatform": "Linux"
}

GitLab CIでの設定例

GitLab CIでPyrightを実行する設定。

.gitlab-ci.yml:

stages:
  - test

python-lint:
  stage: test
  image: python:3.11
  before_script:
    - pip install --upgrade pip
    - pip install pyright
    - pip install -r requirements.txt
  script:
    - pyright --project .
  only:
    - merge_requests
    - main
    - develop
  allow_failure: false  # 型チェックエラーでビルド失敗

pre-commit フックでのローカルチェック

コミット前に自動的に型チェックを実行する設定。

.pre-commit-config.yaml:

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.5.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-added-large-files

  - repo: https://github.com/psf/black
    rev: 23.12.1
    hooks:
      - id: black
        language_version: python3.11

  - repo: https://github.com/RobertCraigie/pyright-python
    rev: v1.1.345
    hooks:
      - id: pyright
        args: [--project, .]

  - repo: https://github.com/pycqa/flake8
    rev: 7.0.0
    hooks:
      - id: flake8
        args: [--max-line-length=88, --extend-ignore=E203]

インストール:

pip install pre-commit
pre-commit install

これにより、git commit実行時に自動的に型チェックが走る。

CI/CD設定のベストプラクティス

型チェックレベルの統一
- ローカル開発環境とCI/CDで同じ設定を使用
- pyrightconfig.jsonで一元管理
段階的な導入
- 最初はwarningのみで実行（allow_failure: true）
- 徐々にエラーを修正し、最終的にallow_failure: falseに
パフォーマンスの最適化
- キャッシュを活用してビルド時間を短縮
- 必要最小限のファイルのみチェック
通知の設定
- CI/CD失敗時にSlackやメールで通知
- プルリクエストにコメントで結果を表示

チーム開発での運用ガイド

複数人でPythonプロジェクトを開発する際の、Pylance設定の統一と運用方法を解説する。

プロジェクト共有設定の作成

チーム全員が同じPylance設定を使用するため、プロジェクトルートに.vscode/settings.jsonを作成する。

.vscode/settings.json（リポジトリにコミット）:

{
  // ===== チーム共通のPylance設定 =====
  "python.languageServer": "Pylance",
  "python.analysis.typeCheckingMode": "basic",

  // ===== 厳格なエラー検出 =====
  "python.analysis.diagnosticSeverityOverrides": {
    "reportUnusedImport": "error",
    "reportUnusedVariable": "error",
    "reportMissingImports": "error"
  },

  // ===== コード補完 =====
  "python.analysis.autoImportCompletions": true,
  "python.analysis.completeFunctionParens": true,

  // ===== フォーマッター設定（チーム統一） =====
  "python.formatting.provider": "none",
  "[python]": {
    "editor.defaultFormatter": "ms-python.black-formatter",
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
      "source.organizeImports": "explicit"
    }
  },

  // ===== Pythonインタープリターパスのヒント =====
  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",

  // ===== 除外設定 =====
  "python.analysis.exclude": [
    "**/node_modules",
    "**/__pycache__",
    ".venv",
    "venv"
  ],

  // ===== テストフレームワーク設定 =====
  "python.testing.pytestEnabled": true,
  "python.testing.unittestEnabled": false
}

.vscode ディレクトリの管理

.gitignore（推奨設定）:

# VSCode設定のうち、個人設定のみ除外
.vscode/*
!.vscode/settings.json     # チーム共有設定はコミット
!.vscode/extensions.json   # 推奨拡張機能もコミット
!.vscode/launch.json       # デバッグ設定もコミット（任意）

推奨拡張機能の指定（.vscode/extensions.json）:

{
  "recommendations": [
    "ms-python.python",           // Python拡張機能（Pylance含む）
    "ms-python.vscode-pylance",   // Pylance（明示的に指定）
    "ms-python.black-formatter",  // Black フォーマッター
    "njpwerner.autodocstring",    // docstring自動生成
    "ms-python.debugpy"           // Pythonデバッガー
  ]
}

チームメンバーがプロジェクトを開くと、VSCodeが推奨拡張機能のインストールを提案する。

チーム内での設定統一のベストプラクティス

1. 設定ファイルのドキュメント化

README.mdやCONTRIBUTING.mdに設定の意図を記載する。

README.md の例:

## 開発環境セットアップ

### 1. VSCode拡張機能のインストール

プロジェクトを開くと、推奨拡張機能のインストールを促すメッセージが表示されます。
以下の拡張機能をインストールしてください:

- Python (ms-python.python)
- Pylance (ms-python.vscode-pylance)
- Black Formatter (ms-python.black-formatter)

### 2. 仮想環境の作成

```bash
python -m venv .venv
source .venv/bin/activate  # Windowsの場合: .venv\Scripts\activate
pip install -r requirements.txt

3. VSCodeでPythonインタープリターを選択

Cmd+Shift+P → "Python: Select Interpreter" → ./.venv/bin/pythonを選択

4. 設定の確認

.vscode/settings.jsonがプロジェクトに含まれているため、 Pylanceの設定は自動的に適用されます。

コーディング規約

型チェックレベル: basic
未使用インポート/変数: エラーとして扱う
フォーマッター: Black
インポート順序: 保存時に自動整理


#### 2. 定期的な設定レビュー

チームミーティングやスプリントレビューで設定を見直す。

**レビューポイント:**
- 型チェックレベルは適切か（`basic` → `strict`への移行検討）
- パフォーマンス問題は発生していないか
- 新しいチームメンバーが困っていないか
- CI/CDとローカル設定の一貫性

#### 3. 段階的な厳格化

プロジェクト開始時は緩めの設定から始め、コードベースが安定してきたら徐々に厳格化する。

**フェーズ1（初期）:**
```json
{
  "python.analysis.typeCheckingMode": "off",
  "python.analysis.diagnosticSeverityOverrides": {
    "reportUnusedImport": "warning"
  }
}

フェーズ2（中期）:

{
  "python.analysis.typeCheckingMode": "basic",
  "python.analysis.diagnosticSeverityOverrides": {
    "reportUnusedImport": "error",
    "reportMissingImports": "error"
  }
}

フェーズ3（成熟期）:

{
  "python.analysis.typeCheckingMode": "strict",
  "python.analysis.diagnosticSeverityOverrides": {
    "reportUnusedImport": "error",
    "reportUnusedVariable": "error",
    "reportMissingImports": "error",
    "reportGeneralTypeIssues": "error"
  }
}

4. コードレビューへの組み込み

プルリクエストのチェックリストにPylanceのエラー解消を含める。

プルリクエストテンプレート（.github/pull_request_template.md）:

## チェックリスト

- [ ] Pylanceのエラーがゼロになっている
- [ ] 未使用のインポートを削除した
- [ ] 型ヒントを適切に追加した
- [ ] CI/CDが成功している
- [ ] コードレビューを受けた

5. 新メンバーへのオンボーディング

新しいチームメンバーがスムーズに開発を始められるよう、セットアップガイドを用意する。

docs/setup-guide.mdの例:

# 開発環境セットアップガイド

## 1. 前提条件

- Python 3.11以降
- Visual Studio Code 1.85以降
- Git

## 2. リポジトリのクローン

```bash
git clone https://github.com/your-org/your-project.git
cd your-project

3. VSCodeで開く

code .

VSCodeが推奨拡張機能のインストールを提案するので、すべてインストールします。

4. 仮想環境のセットアップ

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

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

Cmd+Shift+Pでコマンドパレットを開く
"Python: Select Interpreter"を選択
./.venv/bin/pythonを選択

6. 設定の確認

.vscode/settings.jsonが自動的に適用されます。ステータスバーに「Pylance」と表示されていることを確認してください。

7. よくある質問

Q: Pylanceが動作しない A: Python拡張機能がインストールされているか確認してください。

Q: 大量のエラーが表示される A: 型ヒントが不足している可能性があります。段階的に修正してください。


### チーム開発での注意点

1. **個人設定とプロジェクト設定の分離**
   - プロジェクト共通設定: `.vscode/settings.json`（コミット）
   - 個人設定: ユーザー設定（User Settings）（コミットしない）

2. **設定の強制しすぎに注意**
   - すべてのメンバーが同じ設定である必要はない
   - 最低限の品質基準をプロジェクト設定で担保
   - 個人の好みは各自のUser Settingsで調整可能

3. **コミュニケーション**
   - 設定変更時はチームに通知
   - 理由と期待される効果を説明
   - フィードバックを歓迎する

## トラブルシューティング

### Pylanceが動作しない

**症状:** Pylanceの機能（コード補完、型チェックなど）が動作しない

**原因と対処法:**

1. **Python拡張機能がインストールされていない**
   - 対処法: VSCodeの拡張機能からMicrosoft製「Python」をインストール

2. **他の言語サーバーが有効になっている**
   - 対処法: `settings.json`で`"python.languageServer": "Pylance"`を設定

3. **Pythonインタープリターが選択されていない**
   - 対処法: Cmd+Shift+P → 「Python: Select Interpreter」を実行

4. **Pylance Language Serverがクラッシュしている**
   - 対処法: VSCodeを再起動、または「Reload Window」を実行

### 型チェックエラーが大量に出る

**症状:** 既存のコードを開いたら、大量のエラーが表示される

**原因と対処法:**

1. **型チェックレベルが strict になっている**
   - 対処法: `typeCheckingMode`を`"basic"`または`"off"`に変更

2. **型ヒントが不足している**
   - 対処法: 段階的に型ヒントを追加する、または`typeCheckingMode`を緩和

3. **サードパーティライブラリの型スタブがない**
   - 対処法: `reportMissingTypeStubs`を`"none"`に設定、または型スタブをインストール
   ```bash
   pip install types-requests  # 例: requestsの型スタブ

パフォーマンスが悪い

症状: VSCodeが重い、Pylanceの応答が遅い

原因と対処法:

ワークスペース全体をチェックしている
- 対処法: diagnosticModeを"openFilesOnly"に変更
```
{
  "python.analysis.diagnosticMode": "openFilesOnly"
}
```
インデックス作成中
- 対処法: インデックス作成が完了するまで待つ（初回のみ時間がかかる）

大量のファイルがある

対処法: .vscode/settings.jsonで特定のディレクトリを除外

{
  "python.analysis.exclude": [
    "**/node_modules",
    "**/.venv",
    "**/venv"
  ]
}

自動インポートが動作しない

症状: 未インポートのモジュールが自動的にインポートされない

原因と対処法:

自動インポート機能が無効
- 対処法: autoImportCompletionsをtrueに設定
モジュールが見つからない
- 対処法: Pythonインタープリターのパスを確認、venvを使用している場合は正しく選択されているか確認
モジュールがインストールされていない
- 対処法: pip install <モジュール名>でインストール

よくある質問（FAQ）

Q1: PylanceとPyrightの違いは何か？

A: Pyrightは型チェック専用のツールであり、Pylanceは型チェック（Pyright）を含む包括的な言語サーバーである。Pylanceはコード補完、自動インポート、シンタックスハイライトなど、多くの追加機能を提供する。VSCodeユーザーはPylanceを使用すべきである。

Q2: mypyとPylanceは併用すべきか？

A: 基本的には不要である。Pylanceの型チェックエンジン（Pyright）は高速で正確であり、ほとんどのケースで十分である。ただし、CI/CDパイプラインでmypyを使用している場合は、ローカル開発でもmypyを併用することで一貫性を保てる。

Q3: Pylanceは無料で使えるか？

A: はい、完全に無料である。MicrosoftがオープンソースとしてPylanceを提供している。

Q4: 既存のFlake8やPylintと併用できるか？

A: はい、併用可能である。Pylanceは型チェックとコード補完を担当し、Flake8やPylintはコーディング規約チェックを担当する、という役割分担ができる。ただし、重複する機能もあるため、設定を調整する必要がある場合がある。

Q5: 型ヒントがないコードでもPylanceは使えるか？

A: はい、型ヒントがなくても使える。Pylanceはコード補完、自動インポート、シンタックスハイライトなどの機能を提供するため、型ヒントがないコードでも有用である。ただし、型チェックの恩恵を最大限受けるには、型ヒントの追加を推奨する。

Q6: Jupyterノートブックでも動作するか？

A: はい、VSCodeのJupyter拡張機能と併用することで、Jupyterノートブック（.ipynb）でもPylanceの機能を使用できる。

Q7: リモート開発（SSH、Container）でも使えるか？

A: はい、VSCodeのRemote Development拡張機能と併用可能である。リモート環境でもPylanceはローカルと同様に動作する。

Q8: Pylanceの設定はプロジェクトごとに変えられるか？

A: はい、.vscode/settings.jsonにプロジェクト固有の設定を記述することで、プロジェクトごとに設定を変更できる。グローバル設定はユーザー設定（User Settings）、プロジェクト固有設定はワークスペース設定（Workspace Settings）に記述する。

Q9: 型チェックのレベルはファイルごとに変えられるか？

A: はい、Pythonファイルの先頭に以下のコメントを追加することで、ファイル単位で型チェックレベルを変更できる。

# pyright: basic
# または
# pyright: strict

Q10: Pylanceのアップデート方法は？

A: Python拡張機能のアップデートと同時にPylanceもアップデートされる。VSCodeの拡張機能タブから、Python拡張機能を最新版に更新すればよい。

まとめ

本記事では、VSCodeでPython開発を行う際に最適なリンターであるPylanceについて、導入から詳細な設定方法、チーム開発での運用まで包括的に解説した。

主なポイント

Pylanceを選ぶべき理由:

型チェック（Pyright）+コード補完+自動インポートなど包括的な機能
VSCode公式のPython拡張機能に含まれ、追加インストール不要
高速で大規模プロジェクトにも対応
Microsoft による継続的な開発とサポート

プロジェクト別の設定パターン:

レガシープロジェクト: 型チェックoff、段階的な品質向上
新規プロジェクト: strictモードで最初から高品質を確保
大規模プロジェクト: パフォーマンス重視の設定で快適な開発
学習・個人開発: バランス型で柔軟に開発
Django/Flask: フレームワーク特有の動的属性に対応

CI/CD連携:

GitHub ActionsやGitLab CIでPyrightを実行
pre-commitフックでコミット前に自動チェック
ローカルとCI/CDで設定を統一し、品質を担保

チーム開発での運用:

.vscode/settings.jsonでプロジェクト共通設定を管理
推奨拡張機能を.vscode/extensions.jsonで指定
段階的な厳格化でチーム全体のスキルアップ
README.mdやCONTRIBUTING.mdで設定を文書化
プルリクエストのチェックリストに型チェックを組み込み

効果的な設定:

型チェックレベルは"basic"から開始し、慣れたら"strict"へ
未使用項目を"error"に設定してコードの品質を保つ
型ヒントのインライン表示で型安全性を向上
自動インポートと自動整理で開発効率を向上

他のリンターとの使い分け:

VSCodeユーザーは Pylance 一択
CI/CDではPyrightまたはmypyをコマンドラインで実行
コーディング規約チェックにはFlake8やPylintを併用可能

トラブル対応:

動作しない場合はPythonインタープリターの選択を確認
エラーが大量に出る場合は型チェックレベルを緩和
パフォーマンス問題は診断モードを調整

Pylanceを適切に設定し、チーム全体で運用することで、型安全性の高い、保守性に優れたPythonコードを効率的に書けるようになる。本記事で紹介した設定パターンやCI/CD連携、チーム運用のベストプラクティスを参考に、自分のプロジェクトに最適な環境を構築してほしい。快適なPython開発ライフを送られることを願う。

【2025年版】VSCode Python開発はPylanceで決まり｜設定完全ガイド

目次

要約

この記事を読むことで得られるメリット

この記事を読むのにかかる時間

環境

リンターとは

VSCodeで使用すべきPythonリンター

Pylance vs Pyright vs mypy - 比較表

Pylanceの特徴

1. Microsoft製の公式言語サーバー

2. Pyrightベースの型チェック

3. 包括的な開発支援機能

4. 3つのチェックレベル

インストール方法

ステップ1: Python拡張機能のインストール

ステップ2: Pylanceが有効になっているか確認

基本設定

settings.jsonの開き方

最小限の推奨設定

おすすめの詳細設定

1. 型チェックレベルの設定

2. 未使用項目をエラーとして検出

3. 関数宣言時にカッコを自動挿入

4. 型ヒントをインラインで表示

5. 自動インポートの設定

6. 診断メッセージの詳細度

7. 型スタブの自動検索

8. インポート文の自動整理

完全版settings.json例

プロジェクト別の設定パターン集

パターン1: レガシープロジェクト向け設定

パターン2: 新規プロジェクト向け設定（strict モード）

パターン3: 大規模プロジェクト向け設定（パフォーマンス重視）

パターン4: 学習・個人開発向け設定（バランス型）

パターン5: Django/Flask プロジェクト向け設定

CI/CD連携の設定例

GitHub Actionsでの設定例

GitLab CIでの設定例

pre-commit フックでのローカルチェック

CI/CD設定のベストプラクティス

チーム開発での運用ガイド

プロジェクト共有設定の作成

.vscode ディレクトリの管理

チーム内での設定統一のベストプラクティス

1. 設定ファイルのドキュメント化

3. VSCodeでPythonインタープリターを選択

4. 設定の確認

コーディング規約

4. コードレビューへの組み込み

5. 新メンバーへのオンボーディング

3. VSCodeで開く

4. 仮想環境のセットアップ

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

6. 設定の確認

7. よくある質問

パフォーマンスが悪い

自動インポートが動作しない

よくある質問（FAQ）

Q1: PylanceとPyrightの違いは何か？

Q2: mypyとPylanceは併用すべきか？

Q3: Pylanceは無料で使えるか？

Q4: 既存のFlake8やPylintと併用できるか？

Q5: 型ヒントがないコードでもPylanceは使えるか？

Q6: Jupyterノートブックでも動作するか？

Q7: リモート開発（SSH、Container）でも使えるか？

Q8: Pylanceの設定はプロジェクトごとに変えられるか？

Q9: 型チェックのレベルはファイルごとに変えられるか？

Q10: Pylanceのアップデート方法は？

まとめ

主なポイント