OSセットアップ後に最初にやること！Python venv環境構築とSSH自動アクティベート設定

RaspberryPiやUbuntuにOSをセットアップした後、Pythonで開発を始める前に必ずやっておきたいのが venv（仮想環境） の設定です。
venvを使わずにシステムのPythonへ直接パッケージをインストールしていくと、OSのアップデートや複数プロジェクトのパッケージ管理が混乱してくる原因になります。
本記事では、venvのセットアップ方法とSSH接続時に自動でvenvが有効になる設定まで、Raspberry Pi・Ubuntu 両対応でまとめて解説します。

なぜvenvを設定するのか？

Pythonには「システムPython」と呼ばれるOS自体が管理するPython環境があります。
ここへ自由にパッケージをインストールすると、OSのツールが依存しているライブラリと衝突したり、複数プロジェクトが異なるバージョンのパッケージを必要とするときに両立できなくなることがあります。
venvを使うことでシステムPythonを汚さず、プロジェクト専用のクリーンなPython環境を手軽に作れます。
また最近のUbuntu / Raspberry Pi OS では pip install をシステムPythonに対して直接実行しようとすると 「externally-managed-environment」エラー が出るようになっており、venvの使用が事実上必須になっています。

OSセットアップ直後にvenvを仕込んでおけば、あとから手戻りがなくなる！

実現したいこと

この記事でわかること

必要な準備と用意するもの

venvの仕組み

venv（virtual environment）はPythonの標準機能で、プロジェクトごとに独立したPython実行環境を作るための仕組みです。

venvを作成すると、指定したフォルダ以下に bin/・lib/・include/ などのディレクトリが作られ、その中に独立したPython実行ファイルと pip が配置されます。
venvをアクティベートすると、python や pip コマンドがシステムのものではなくvenv内のものを参照するようになります。

# アクティベート前：システムのPythonを参照
which python3
# → /usr/bin/python3

# アクティベート後：venv内のPythonを参照
source ~/venv/smarthome/bin/activate
which python3
# → /home/<username>/venv/smarthome/bin/python3

プロジェクトごとにvenvを分けるべきか？

「本来はプロジェクト（アプリ）ごとに個別のvenvを作るべきでは？」という疑問はもっともです。
結論から言うと、個人開発・スマートホーム用途であれば1つのvenvにまとめて問題ないと考えています。以下にそれぞれのメリット・デメリットを整理します。

プロジェクトごとに個別venvを作る場合

依存関係の完全な分離
プロジェクトAが requests==2.28、プロジェクトBが requests==2.31 を必要とする場合でも、それぞれのvenvで独立したバージョンを保持できる

requirements.txtによる再現性
pip freeze > requirements.txt で特定プロジェクトの依存パッケージだけを記録でき、別の環境への移植や復元が容易

管理の煩雑さ
スクリプトを実行するたびに「どのvenvをアクティベートすべきか」を意識しなければならない。systemd などの自動実行設定でも各サービスごとにPythonのフルパスを指定する必要がある

ディスク使用量の増大
venvごとにPython本体のコピーやパッケージが保存されるためディスクを多く消費する（Raspberry Piのようにストレージが限られる環境では地味に影響する）

1つのvenvに全プロジェクトをまとめる場合

シンプルな管理
SSH接続後に自動でアクティベートしておけば、あとは python script.py とするだけでどのスクリプトも動く。systemdのサービスファイルも同じvenvのパスを指定するだけでよい

パッケージの共有による効率化
requests や influxdb-client など複数のスクリプトで使う共通ライブラリを1回インストールするだけで済む

パッケージバージョンの競合リスク
同じライブラリの異なるバージョンを同時に必要とするプロジェクトが現れた場合に対応できない（ただしスマートホームの個人開発で実際にこのケースに陥ることは稀）

当ラボの結論：個人のスマートホーム開発なら1つのvenvで十分
スマートホームのスクリプト群はいずれも同じ目的（自宅の自動化）のために動き、使うライブラリも requests・influxdb-client・flask などが共通になりやすいです。同じライブラリの異なるバージョンが必要になる状況はほぼ起きません。「本来はプロジェクトごとに分けるべき」という原則は正しいですが、複雑さが増すコストの方が高くつくケースも多いです。そのため当ラボでは、シンプルさを優先して1つのvenvにまとめる構成をおすすめしています。。もし将来的に特定のプロジェクトだけ特殊なバージョンが必要になったときに、そのプロジェクト専用のvenvに切り出せばよいです。

事前準備

python3-venv のインストール

Ubuntu / Raspberry Pi OS では python3-venv が標準でインストールされていない場合があります。まずインストールします。

sudo apt update
sudo apt install -y python3-venv python3-pip

インストール済みのPythonバージョンを確認します。

python3 --version

venvのセットアップ

venv の作成

ホームディレクトリ配下に venv フォルダを作り、その中に仮想環境を作成します。
環境名（ここでは smarthome）は自由に決めてください。

mkdir -p ~/venv
python3 -m venv ~/venv/smarthome

作成されたフォルダ構成を確認します。

ls ~/venv/smarthome/
# → bin  include  lib  lib64  pyvenv.cfg

venv の手動アクティベートと動作確認

まず手動でアクティベートして動作を確認します。

source ~/venv/smarthome/bin/activate

アクティベートに成功するとプロンプトの先頭に (smarthome) と表示されます。

(smarthome) <username>@nucbox-server:~$

この状態で pip install を実行するとvenv内にパッケージがインストールされ、システムPythonへの影響はありません。

# 試しによく使うパッケージをインストール
pip install requests

# インストールされたパッケージの確認
pip list

venvを無効化するときは deactivate コマンドを実行します。

deactivate

SSH 接続時にvenvを自動アクティベートする

毎回 source ~/venv/smarthome/bin/activate を実行するのは手間です。
~/.bashrc に追記しておくことで、SSH接続後・ターミナルを開いたときに自動でアクティベートされます。

echo 'source ~/venv/smarthome/bin/activate' >> ~/.bashrc

追記内容を確認します。

tail -3 ~/.bashrc

設定を即座に反映します。

source ~/.bashrc

~/.bashrc はインタラクティブシェル（ターミナルやSSHセッション）起動時に読み込まれます。SSH接続するだけで自動的にvenvがアクティベートされるため、以降は手動でアクティベートする必要はありません。

systemd サービスからvenvを使う場合

Pythonスクリプトを systemd で自動実行する場合、.bashrc の設定は読み込まれません。
サービスファイルの ExecStart にvenv内の Python フルパスを直接指定する必要があります。

[Unit]
Description=My Smarthome App

[Service]
ExecStart=/home/<username>/venv/smarthome/bin/python /home/<username>/projects/smarthome/myapp.py
WorkingDirectory=/home/<username>/projects/smarthome
Restart=always
User=<username>

[Install]
WantedBy=multi-user.target

systemd サービスは .bashrc や source activate を読まないため、ExecStart には必ずvenv内のPythonフルパス（/home/<username>/venv/smarthome/bin/python）を指定してください。python3 とだけ書くとシステムのPythonが実行されvenvのパッケージが使えません。

動作確認

SSH接続後の自動アクティベートを確認

一度ターミナルを閉じてから再度SSH接続し、プロンプトを確認します。

# SSH接続直後のプロンプト確認
# → (smarthome) <username>@nucbox-server:~$  ← (smarthome) が表示されていればOK

# venv内のPythonが使われていることを確認
which python3
# → /home/<username>/venv/smarthome/bin/python3

# venv内のpipが使われていることを確認
which pip
# → /home/<username>/venv/smarthome/bin/pip

パッケージのインストールと確認

venv内にパッケージをインストールし、スクリプトから使えることを確認します。

pip install requests
python3 -c "import requests; print(requests.__version__)"
# → 2.xx.x  ← バージョンが表示されればOK

プロンプトに (smarthome) が表示され、which python3 でvenv内のパスが返ってくれば設定完了です。以降はSSH接続するだけでvenvが有効になります。

インストール済みパッケージの一覧を保存する（任意）

後から別のマシンに同じ環境を再現したい場合は requirements.txt として保存しておくと便利です。

# 現在インストール済みのパッケージを保存
pip freeze > ~/venv/requirements.txt

# 別のマシンで同じ環境を再現する場合
pip install -r ~/venv/requirements.txt

まとめ

OSセットアップ後に最初にやっておくべきPython venv の設定手順をまとめました。

この設定をOSセットアップの直後にやっておくだけで、以降のPython開発がぐっとスムーズになります。
Raspberry Pi でも Ubuntu でも全く同じ手順で設定できるため、複数のマシンで環境を統一するのも簡単です。