かんたんPython環境構築

はじめに

最小手順の環境構築から、迷わないディレクトリ構成、すぐ試せる活用例までを1本にまとめました。

前提

• Python 3.10+ を1つだけ入れておくこと
  Windows：公式インストーラ（python.org）
  macOS：python.org または brew install python@3
• ターミナル（PowerShell / zsh / bash）が使えること
  補足：PowerShellでスクリプト実行がブロックされる場合は、管理者で Set-ExecutionPolicy -Scope CurrentUser RemoteSigned を設定

0. Pythonのパス確認とPATHを確認

Windows

一時的に PATH を通す（現在の PowerShell セッションだけ）

$env:Path += ";C:\Users\you\AppData\Local\Programs\Python\Python311\"
$env:Path += ";C:\Users\you\AppData\Local\Programs\Python\Python311\Scripts\"

永続的に PATH を通す（ユーザー環境変数）
　- Windows 検索 →「環境変数」→「環境変数の編集」
　- 「ユーザー環境変数」→ Path を編集 → 下記を追加

C:\Users\you\AppData\Local\Programs\Python\Python311\
C:\Users\you\AppData\Local\Programs\Python\Python311\Scripts\

macOS

Homebrew のパスを通す : Apple Silicon (M1/M2/M3)

echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zprofile
exec $SHELL -l

Homebrew のパスを通す : Intel Mac

echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.zprofile
exec $SHELL -l

その後、which python3 が /opt/homebrew/bin/python3（または /usr/local/bin/python3）を指すかを確認する。

1. プロジェクトを作る（venvだけでOK）

※ポイント：プロジェクトごとに .venv を置くと、依存が混ざりません。

# 任意の親フォルダで
mkdir myapp && cd myapp

# 仮想環境を作成（Windows は Scripts、macOS/Linux は bin）
python -m venv .venv

# 有効化（無効化は deactivate）
# Windows (PowerShell)
. .\.venv\Scripts\Activate.ps1
# macOS/Linux
source .venv/bin/activate

# ツールを更新
python -m pip install --upgrade pip

2. 最小の依存関係

※ポイント：後から別PCで再現する時はpip install -r requirements.txtでOK

# 開発でよく使う最小セット
pip install requests fastapi uvicorn pytest

# 依存を記録（共有しやすい）
pip freeze > requirements.txt

3. ディレクトリ構成（小〜中規模用）

myapp/
├─ .venv/                # 仮想環境（Gitに入れない）
├─ app/                  # アプリ本体
│  ├─ __init__.py
│  ├─ main.py            # CLIのエントリ
│  ├─ api.py             # Web API(FastAPI)のエントリ
│  └─ utils/             # 汎用関数
│     └─ io.py
├─ tests/                # テスト
│  └─ test_main.py
├─ notebooks/            # Jupyterノート用（分析/試行）
├─ .gitignore
├─ requirements.txt
└─ README.md

.gitignore（抜粋）

.venv/
__pycache__/
*.pyc
.ipynb_checkpoints/

※秘密情報（APIキー等）は .env に置き、必ずGit管理外にすること

4. 活用例

4-1. CLIスクリプト

import sys
import requests

def get_json(url: str) -> dict:
    res = requests.get(url, timeout=10)
    res.raise_for_status()
    return res.json()

if __name__ == "__main__":
    url = sys.argv[1] if len(sys.argv) > 1 else "https://httpbin.org/json"
    data = get_json(url)
    print(f"[OK] keys={list(data.keys())}")

実行

python app/main.py
python app/main.py https://httpbin.org/anything

4-2. Web API

app/api.py

from fastapi import FastAPI

app = FastAPI()

@app.get("/health")
def health():
    return {"ok": True}

起動

uvicorn app.api:app --reload --port 8000
# => http://127.0.0.1:8000/docs に自動ドキュメント

uvicornは有効化したvenv内にインストールされています。
VS Codeを使う場合は、左下のインタプリタ選択で.venvを選ぶと楽です。

4-3. 単体テスト

tests/test_main.py

from app.main import get_json

def test_get_json_ok():
    data = get_json("https://httpbin.org/json")
    assert "slideshow" in data

実行

pytest -q

※外部HTTPに依存するテストはネットワーク状態で落ちることがあります。

5. 環境変数（秘密情報の管理）

pip install python-dotenv

.env

API_KEY=xxxxxxxx

app/utils/io.py

import os
from dotenv import load_dotenv

load_dotenv()
API_KEY = os.getenv("API_KEY", "")

よくある問題と解決方法

• python が別バージョンを指す
  原因 : PATH 衝突
  解決 : python --versionを確認し、必要ならpy -3.11で明示
• 依存が壊れた
  原因 : venvが古い or 混在
  解決 : .venvを削除 → 作り直し → pip install -r requirements.txt
• uvicorn が見つからない
  原因 : venv未有効化
  解決 : venv を有効化してからpip install
• 証明書/SSLエラー
  原因 : CA設定不足
  解決 : CA証明書をOS/certifiに登録 or Proxy設定を見直し

必要になったら検討

• uv：再現性と速度が必要になったら、pipの代替として使用
• pre-commit / ruff / mypy / pyright：品質チェックを自動化
• Docker：配布・本番運用時のみコンテナ化