仮想環境とは

Pythonパッケージをプロジェクトごとに独立した場所にインストールする仕組みです。

システム全体 (触らない)
├── Python 3.13
└── apt管理のパッケージのみ

~/unicorn-env/  ← 仮想環境
├── bin/python   ← この環境専用のPython
├── bin/pip
└── lib/
    └── unicornhat, RPi.GPIO, spidev ...

システムのPythonを汚さずに、好きなパッケージを入れられます。

---

なぜ Bookworm から必要になったか

Raspberry Pi OS Bookworm（2023年リリース）から、Debian のルールに従いシステムのPythonへの直接インストールが禁止されました。理由はOSが管理するパッケージと、pip でインストールしたパッケージが衝突してOSが壊れる事故が多発したためです。

〜 Bullseye まで          Bookworm 以降
─────────────────         ─────────────────────
pip install なんでもOK  →  仮想環境の中だけOK
（OSが壊れることも）       （OSは安全）

---

基本的な使い方

# 作成（初回一度だけ）
python3 -m venv ~/unicorn-env

# 有効化（ターミナルを開くたびに必要）
source ~/unicorn-env/bin/activate
# → プロンプトが (unicorn-env) pi@raspberrypi:~ $ に変わる

# この状態で pip install すると仮想環境内に入る
pip install unicornhat

# 実行
python unicorn_clock.py

# 無効化（仮想環境を抜ける）
deactivate

---

複数プロジェクトへの応用

プロジェクトごとに環境を分けられるのが最大のメリットです。

~/unicorn-env/     unicornhat 専用
~/flask-env/       Webアプリ用
~/ml-env/          TensorFlow用（バージョンが違っても衝突しない）

たとえば unicornhat は Python 3.9 が必要で、別のプロジェクトは Python 3.13 が必要、という場合も共存できます。

---

sudo と仮想環境の関係

今回ハマったのがこの点です。

# ❌ これは /usr/bin/python（システム）で実行される
sudo python unicorn_clock.py

# ✅ 仮想環境のPythonをフルパスで指定する
sudo ~/unicorn-env/bin/python unicorn_clock.py

sudo はセキュリティ上、ユーザーの PATH や仮想環境を引き継がないため、仮想環境を有効化していても素のPythonが呼ばれてしまいます。

---

よく使うコマンドまとめ

# 今の環境に何が入っているか確認
pip list

# 環境を別のPCに再現するためにリスト出力
pip freeze > requirements.txt

# requirements.txt から一括インストール
pip install -r requirements.txt

# 仮想環境を削除したいとき（フォルダごと消すだけ）
rm -rf ~/unicorn-env