全体の流れ

Python の開発環境構築は、次の7ステップで完成します。 初回は少し手順が多く感じますが、一度やれば次からは 仮想環境を作る→有効化する→pip でインストールの3ステップだけになります。

  • Python 本体のインストール

    公式サイトからインストーラをダウンロードして実行する(Windows)、または Homebrew を使う(macOS)。

  • インストール確認

    ターミナルで python --version を実行してバージョンが表示されれば OK。

  • 仮想環境(venv)を作成・有効化

    プロジェクトごとに独立したパッケージ管理環境を用意する。

  • pip でパッケージをインストール

    仮想環境に入った状態で pip install を実行する。

  • VSCode の設定

    Python 拡張機能を入れ、インタープリタを仮想環境に向ける。

  • Hello World で動作確認

    スクリプトを書いて実行し、環境が正しく動くことを確認する。

  • requirements.txt で環境を記録

    依存パッケージを1ファイルに書き出し、チームメンバーや別PCで再現できるようにする。

💡 動作確認済みバージョン

Python 3.12 / Windows 11・macOS 14 Sonoma で確認済みです。コマンドの細部が異なる場合はバージョン差異によるものです。

① Python のインストール

OS によってインストール方法が異なります。タブで切り替えてください。

# 1. 公式サイト https://www.python.org/downloads/ から
#    最新の Windows installer (64-bit) をダウンロードする

# 2. インストーラを実行する際に必ず確認するオプション:
#    ✅ Add Python to PATH   ← これを忘れると後で詰まる

# 3. "Install Now" をクリックして完了

# 4. インストール後、PowerShell (管理者) を開いて確認
python --version
# → Python 3.12.x と表示されれば OK
# Homebrew がない場合は先にインストール
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Homebrew で Python をインストール
brew install python

# シェルを再起動してから確認
python3 --version
# → Python 3.12.x と表示されれば OK

# ※ macOS には /usr/bin/python3 (Apple 付属) が存在する場合があります。
#   brew でインストールした python3 が優先されるよう PATH を確認してください。
# パッケージリストを更新
sudo apt update

# Python 3 と pip をインストール
sudo apt install -y python3 python3-pip python3-venv

# バージョン確認
python3 --version
pip3 --version

⚠️ Windows で python が見つからない場合

「Add Python to PATH」にチェックを入れ忘れた可能性があります。コントロールパネル → システム → 詳細設定 → 環境変数 から Path に Python のインストールフォルダ(例: C:\Users\ユーザー名\AppData\Local\Programs\Python\Python312\)を追加するか、インストーラを再実行して「Modify」→「Add Python to PATH」を有効にしてください。

② インストール確認

ターミナル(PowerShell / Terminal.app)を開いて、次のコマンドを実行します。

Shell — バージョン確認
# Python 本体のバージョン
python --version        # Windows
python3 --version       # macOS / Linux

# pip のバージョン(パッケージ管理ツール)
pip --version           # Windows
pip3 --version          # macOS / Linux

期待する出力例:

出力例
Python 3.12.3
pip 24.0 from /usr/local/lib/python3.12/site-packages/pip (python 3.12)
系統 バージョン ステータス 備考
Python 3.12.x 最新安定版 推奨 本記事の動作確認バージョン
Python 3.11.x 旧安定版 OK ほぼすべてのライブラリが対応済み
Python 3.10.x 以下 古い版 非推奨 セキュリティ更新が終了したバージョンあり
Python 2.x 旧世代 使用不可 2020年にサポート終了。新規プロジェクトでは使わない

③ 仮想環境(venv)の作成と有効化

Python では複数のプロジェクトを同じPC上で進めることが多く、プロジェクトごとに異なるバージョンのライブラリが必要になる場合があります。 仮想環境はプロジェクト専用のパッケージ置き場を作る仕組みで、環境を汚染せずに安全に開発できます。

venv は Python 標準機能

追加インストール不要で Python 3.3 以降に標準搭載されています。新しいプロジェクトを始めるたびに仮想環境を作るのが現代のベストプラクティスです。

# 1. プロジェクトフォルダに移動
cd C:\Users\ユーザー名\projects\my-project

# 2. 仮想環境を作成(.venv というフォルダが作られる)
python -m venv .venv

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

# ターミナルの先頭に (.venv) と表示されれば有効化完了
# (.venv) PS C:\Users\ユーザー名\projects\my-project>

# 仮想環境を終了するとき
deactivate
# 1. プロジェクトフォルダに移動
cd ~/projects/my-project

# 2. 仮想環境を作成(.venv というフォルダが作られる)
python3 -m venv .venv

# 3. 仮想環境を有効化
source .venv/bin/activate

# ターミナルの先頭に (.venv) と表示されれば有効化完了
# (.venv) user@hostname my-project %

# 仮想環境を終了するとき
deactivate

⚠️ Windows PowerShell でスクリプト実行が禁止されている場合

Activate.ps1 は、このシステムではスクリプトの実行が無効... というエラーが出たら、PowerShell を管理者で開いて以下を実行してください。

PowerShell — 実行ポリシー変更
# 現在のユーザーに対して実行ポリシーを緩和する
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# 確認プロンプトに Y で答える
# 再度 Activate.ps1 を実行する

④ pip でパッケージをインストール

pip は Python の標準パッケージ管理ツールです。 仮想環境を有効化した状態で実行すると、その環境専用のフォルダにインストールされます。

Shell — pip 基本コマンド
# パッケージをインストール
pip install requests

# バージョンを指定してインストール
pip install requests==2.31.0

# 複数まとめてインストール
pip install requests numpy pandas

# インストール済みパッケージ一覧を確認
pip list

# パッケージの詳細情報を確認
pip show requests

# パッケージをアンインストール
pip uninstall requests

# pip 自体をアップグレード
pip install --upgrade pip

よく使われるパッケージを紹介します。

パッケージ名 用途 インストールコマンド
requests HTTP リクエスト(APIコール・Webスクレイピング) pip install requests
numpy 数値計算・配列操作 pip install numpy
pandas データ分析・CSV操作 pip install pandas
flask 軽量 Web フレームワーク pip install flask
fastapi 高速 API フレームワーク pip install fastapi uvicorn
pytest テストフレームワーク pip install pytest

⑤ VSCode の設定

Visual Studio Code(VSCode)は Python 開発でもっとも広く使われているエディタです。公式の Python 拡張機能を入れるだけで補完・デバッグ・Lintが使えるようになります。

  • Python 拡張機能のインストール

    VSCode の拡張機能ビュー(Ctrl+Shift+X)を開き、「Python」(Microsoft 製)を検索してインストールする。

  • インタープリタを仮想環境に設定

    Ctrl+Shift+P(Mac: ⌘+Shift+P)でコマンドパレットを開き、「Python: Select Interpreter」を実行。リストから .venv のインタープリタを選ぶ。

  • settings.json に保存(オプション)

    プロジェクト直下の .vscode/settings.json に書いておくとチームで共有できる。

JSON — .vscode/settings.json
{
  // 仮想環境のインタープリタを指定(Windows)
  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/Scripts/python.exe",

  // macOS / Linux の場合
  // "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",

  // ファイル保存時に自動フォーマット
  "editor.formatOnSave": true,
  "[python]": {
    "editor.defaultFormatter": "ms-python.black-formatter"
  },

  // Linter の設定(ruff を推奨)
  "python.linting.enabled": true,

  // ターミナルで仮想環境を自動有効化
  "python.terminal.activateEnvironment": true
}

おすすめ追加拡張機能

  • Pylance — 高精度な型チェック・補完(Python 拡張に同梱)
  • Black Formatter — コードの自動フォーマット
  • Ruff — 高速 Linter(flake8 + isort の代替)
  • GitLens — Git 操作の強化

⑥ Hello World で動作確認

プロジェクトフォルダに hello.py を作成し、実行して動作を確認します。

Python — hello.py
#!/usr/bin/env python3
"""
Hello World — 開発環境の動作確認スクリプト
"""

# 基本的な出力
print("Hello, World!")

# Python のバージョンを確認
import sys
print(f"Python バージョン: {sys.version}")

# 現在の仮想環境パスを確認
import os
print(f"仮想環境: {os.environ.get('VIRTUAL_ENV', '(仮想環境なし)')}")

# requests がインストールされているか確認(先に pip install requests が必要)
try:
    import requests
    print(f"requests バージョン: {requests.__version__}")
except ImportError:
    print("requests は未インストールです。 pip install requests で追加できます。")
Shell — スクリプトの実行
# 仮想環境が有効な状態で実行する
python hello.py

# 期待する出力:
# Hello, World!
# Python バージョン: 3.12.3 (main, ...)
# 仮想環境: /path/to/my-project/.venv

⑦ requirements.txt で環境を再現

開発中にインストールしたパッケージをファイルに書き出しておくことで、 チームメンバーや別のPCでも同じ環境を1コマンドで再現できます。

Shell — requirements.txt の生成と利用
# 現在の環境のパッケージをファイルに書き出す
pip freeze > requirements.txt

# 内容の確認(例)
# requests==2.31.0
# numpy==1.26.4
# pandas==2.2.1

# 別の環境で同じパッケージをまとめてインストール
pip install -r requirements.txt

💡 pip freeze の注意点

pip freeze は間接依存も含めた全パッケージを出力します。直接インストールしたパッケージだけ管理したい場合は pip-toolspip-compilePoetry を検討してください。

よくあるトラブルと対処

python コマンドが認識されない(Windows)

インストール時に「Add Python to PATH」を有効にしなかった場合に起きます。

PowerShell — PATH の確認と追加
# Python がどこにインストールされているか確認
where python   # 見つからなければ PATH 未設定

# インストールパスを環境変数に追加(ユーザー単位)
# 例: Python 3.12 を C:\Users\ユーザー名\AppData\Local\Programs\Python\Python312 にインストールした場合
[System.Environment]::SetEnvironmentVariable(
  "Path",
  $env:Path + ";C:\Users\ユーザー名\AppData\Local\Programs\Python\Python312\;C:\Users\ユーザー名\AppData\Local\Programs\Python\Python312\Scripts\",
  "User"
)
# PowerShell を再起動して python --version で確認

pip install が遅い・タイムアウトする

社内プロキシ環境や海外向けネットワークの場合、ミラーサーバーを指定すると改善することがあります。

Shell — PyPI ミラーを指定
# 国内ミラー(JAIST)を一時的に使用
pip install requests -i https://ftp.jaist.ac.jp/pub/pypi/simple/

# pip.ini / pip.conf に常時設定する場合
# Windows: %APPDATA%\pip\pip.ini
# macOS/Linux: ~/.pip/pip.conf
[global]
index-url = https://ftp.jaist.ac.jp/pub/pypi/simple/

ModuleNotFoundError が出る

仮想環境の外でインストールしたか、仮想環境を有効化し忘れている可能性があります。

Shell — 確認手順
# 1. 仮想環境が有効かターミナルのプロンプトで確認
#    (.venv) が先頭に付いていれば有効

# 2. 実際にどの Python が使われているか確認
which python   # macOS/Linux
where python   # Windows

# 3. パッケージが入っているか確認
pip list | grep requests

# 4. 仮想環境に入り直してインストール
source .venv/bin/activate   # macOS/Linux
.\.venv\Scripts\Activate.ps1  # Windows
pip install requests

環境構築チェックリスト

  • python --version でバージョンが表示される
  • pip --version で pip が動く
  • .venv フォルダが作成されている
  • ターミナルのプロンプトに (.venv) が表示されている
  • VSCode のステータスバーに仮想環境のインタープリタが表示されている
  • python hello.py で「Hello, World!」が出力される
  • requirements.txt が作成されている