Raspberry Pi OS では、通常の GPIO プログラムを root で動かす必要はありません。公式の要件は、GPIO を使うアカウントが gpio グループに所属することです。対象アカウントを追加し、実際に新しいログインセッションを開始して、有効なプロセス ID を確認してから次を調べます。
この 2026 年メンテナンス層では、古い記事にあった /dev/mem の権限変更を推奨から削除しました。デバイスノードは OS が管理するセキュリティ境界であり、物理メモリへの広いアクセスを与えることは GPIO の修復ではありません。2019 年の本文は、明確に区切ったアーカイブとして末尾に保存しています。
Table of Contents
1. 失敗した正確な実行コンテキストから始める
実際に失敗したマシン、アカウント、プログラム、起動経路を記録します。
cat /etc/os-release
uname -a
cat /proc/device-tree/model 2>/dev/null || true
id
command -v python3
python3 --version失敗したプログラムと同じコンテキストで実行してください。対話型 SSH、デスクトップ端末、systemd サービス、cron、コンテナ、リモート開発ツールでは、アカウントやデバイスアクセスが異なることがあります。ログを公開する前にホスト名とアカウント名を伏せます。
最初から sudo を付けないでください。root のときだけ成功すると、本来の権限境界が隠れ、プロジェクトや仮想環境に root 所有ファイルを作ることもあります。
2. グループ所属を二つの場所で確認する
まず gpio グループの存在と、ユーザーデータベースに記録されたアカウントを確認します。alice を、実際の非 root ログインまたはサービスアカウントへ一度置き換えてください。
gpio_user="alice"
getent passwd "$gpio_user"
getent group gpio
id "$gpio_user"次に、現在のプロセスで有効なグループを確認します。
id
id -nG両者は別の問いに答えます。id alice に新しい所属が表示されても、古い端末はその補助グループをまだ持たないことがあります。カーネルが調べるのは、現在の /etc/group の内容だけでなく、実行プロセスに付随するグループです。
3. 必要なグループだけを追加する
対象アカウントに gpio がなければ、Raspberry Pi の公式文書にあるコマンドを使います。
sudo usermod -a -G gpio "$gpio_user"-a は重要です。既存の補助グループを置き換えず、gpio を追加します。GPIO を使うためだけに sudo や無関係な多数のデバイスグループを与えないでください。
ここでログインセッションを完全に終了して再ログインします。SSH なら関連セッションを切断して接続し直し、デスクトップならデスクトップセッション全体からログアウトします。システム上安全なら、再起動も単純な選択肢です。同じ古いデスクトップセッション内で端末をもう一つ開いても、古いグループ一覧を継承することがあります。
新しいログイン後に有効な結果を確認します。
id -nG失敗したプロセスの ID に gpio が現れてから先へ進みます。
4. デバイスノードを調べ、書き換えない
現在の GPIO ライブラリは、一般に /dev/gpiochip0 などの Linux GPIO キャラクターデバイスを使います。古いバックエンドは GPIO に限定した /dev/gpiomem を使うことがあります。稼働中の OS が何を作成したか調べます。
ls -l /dev/gpiochip* /dev/gpiomem 2>/dev/null
stat -c '%n owner=%U group=%G mode=%A type=%F'
/dev/gpiochip* /dev/gpiomem 2>/dev/nullRaspberry Pi OS では通常、インストール済みパッケージとデバイス規則がこれらを gpio グループ向けに管理します。全員が書き込めるようにせず、起動スクリプトで chmod や chown を繰り返さないでください。手作業の変更は OS、パッケージ、設定の問題を示すことがあり、再起動で消えるうえ、隔離を弱めます。
最新状態の Raspberry Pi OS で所有者が予想外なら、修復前に出力、インストール済み GPIO パッケージ、ローカル udev 規則を記録します。古いフォーラムのコマンドから永続規則を推測してはいけません。
5. 現行の GPIO インターフェースを使う
Raspberry Pi OS 上の Python アプリケーションでは、GPIO Zero が保守中の高レベルな出発点です。ディストリビューションから導入し、仮想環境からシステムのハードウェアバインディングを参照できるようにします。
sudo apt update
sudo apt install --yes python3-gpiozero python3-venv gpiod
python3 -m venv .venv --system-site-packages
. .venv/bin/activate
python -c 'from importlib.metadata import version; print(version("gpiozero"))'GPIO ラインを要求せず、カーネルの GPIO チップを一覧します。
gpiodetectGPIO Zero は lgpio を含む対応 pin factory を文書化された順序で試します。アプリケーションが factory を固定するなら、その選択を記録し、実際の Raspberry Pi モデルで検証してください。Raspberry Pi 5 の GPIO アーキテクチャは旧世代と異なるため、Unix 権限が正しくても古いレジスター直アクセスのライブラリは失敗することがあります。
6. 権限と Python 環境を分ける
Python 仮想環境の有効化・無効化は Python の実行ファイルとパッケージを変えますが、実行中プロセスに Linux の補助グループを追加しません。deactivate を権限修復とみなさず、インタープリターとパッケージを比較します。
id -nG
command -v python
python --version
python -c 'import sys; print(sys.executable)'
python -c 'from gpiozero import Device; print(Device.pin_factory)'GPIO Zero は factory を遅延作成するため、最初の Device.pin_factory は None になる場合があります。モジュール欠落、BadPinFactory、未対応ボードのエラーは Python／バックエンド層を示します。存在するデバイスノードを開く際の Permission denied は、プロセス ID またはサービス／コンテナポリシーを示します。
GPIO Zero の mock factory を使えば、ハードウェアなしで純粋なアプリケーションロジックを確認できます。
GPIOZERO_PIN_FACTORY=mock python - <<'PY'
from gpiozero import LED
with LED(17) as led:
led.on()
assert led.value == 1
print("mock GPIO test passed")
PYこの成功は Python 側ロジックが開始できることだけを示し、実デバイスの権限、配線、電圧、タイミングは証明しません。
7. サービスアカウントとして診断する
systemd サービスは端末のアカウントを使わないことがあります。宣言されたコンテキストと有効なコンテキストを調べます。
systemctl show my-gpio-app.service
-p User -p Group -p SupplementaryGroups -p DynamicUser -p DevicePolicy
systemctl status my-gpio-app.service
journalctl -u my-gpio-app.service -b --no-pager例の unit 名を置き換えてください。サービスの User= アカウントは gpio に所属する必要があります。unit に SupplementaryGroups=gpio を明記すれば、その要件自体も記録できます。unit 編集後は sudo systemctl daemon-reload を実行し、そのサービスだけを再起動します。
ハードニング設定も確認します。厳しい DevicePolicy=、PrivateDevices=、コンテナ状のサンドボックスは、意図的に GPIO デバイスを隠したり拒否したりします。すべてのサービス隔離を無効にせず、必要最小限のアクセスを維持してください。
8. コンテナとリモートマシンを別の境界として扱う
コンテナはホストの GPIO デバイスやグループ対応を自動では受け取りません。Docker は --device で個別のホストデバイスを渡し、--group-add で補助グループを追加できます。必要な /dev/gpiochipN とホストの GPIO グループ ID だけを割り当てます。GPIO よりはるかに広い権限を与える --privileged は避けてください。
WSL、通常の仮想マシン、リモート実行するノート PC には、ローカル Raspberry Pi GPIO デバイスが存在しない場合があります。その場合はテストに mock pins を使うか、意図して構成したリモート GPIO サービスを使います。Pi 以外のコンピューターで権限を変えても、存在しないハードウェアは作れません。
9. エラーの種類から次の確認を選ぶ
| エラーまたは症状 | 一般的な意味 | 次に集める証拠 |
|---|---|---|
/dev/gpiochip* または /dev/gpiomem を開く際の Permission denied | プロセスに有効なグループがないか、サービス／コンテナポリシーがノードを拒否 | id -nG、ノードの ls -l、サービス／コンテナ設定 |
No such file or directory | プラットフォーム違い、コンテナで非表示、ドライバー／パッケージ欠落、古いノードを期待するバックエンド | ボード／OS ID、/dev/gpio*、バックエンド版 |
Device or resource busy | 別プロセスまたはカーネルドライバーが対象 line を所有 | gpioinfo、実行中サービス、HAT／overlay 文書 |
BadPinFactory | GPIO Zero が互換バックエンドをロードできない | GPIO Zero 版、factory パッケージ、正確なボードモデル |
| ボード、peripheral base、SoC が不明 | レジスター直アクセスのライブラリがボードに対して古い | 現行 GPIO Zero/lgpio、または版の合うキャラクターデバイス方式へ移行 |
| 対話実行は成功し、サービスだけ失敗 | アカウント、グループ、環境、作業ディレクトリ、サンドボックスが異なる | systemctl show、journal、サービスユーザーの id |
すべての失敗を権限変更へ置き換えないでください。「busy」「missing」「unsupported」「denied」は別々の境界です。
10. /dev/mem の権限拡大を GPIO の回避策にしない
/dev/mem は GPIO 周辺機器をはるかに超える物理メモリを公開します。グループ書き込み可能にすると、そのグループの全メンバーへ広いシステム能力を渡し、カーネルの通常の GPIO 所有モデルを迂回します。そのため、古い記事の /dev/mem 用 chown と chmod は歴史的証拠としてのみ残し、実行してはいけません。
ライブラリが raw memory を要求する、または root でしか動かない場合は、まずボードに対して古くなっていないか確認します。対応 pin factory を使う GPIO Zero、または版の合う libgpiod アプリケーションを優先してください。専用製品が本当に raw access を必要とするなら、その脅威境界を別に文書化しレビューします。これは一般ユーザーの通常修復ではありません。
11. アクセス修復後にハードウェアを安全に検証する
権限が正しくても回路が安全とは限りません。Raspberry Pi GPIO は 3.3 V ロジックです。GPIO 入力へ 5 V を入れず、LED には電流制限抵抗を使い、GPIO からモーターを直接駆動しないでください。適切なコントローラーまたは H ブリッジを使います。
交換可能で低エネルギーのテスト回路を接続する前に pinout を実行し、BCM 番号と物理番号を確認します。配線変更前に電源を切ります。最小の LED または入力テストが成功してから、大きな負荷をアプリケーションで制御してください。
12. 2019 年の元記事アーカイブ
以下のブロックは 2019 年の英語本文全体です。行末空白の正規化を除き、言葉とコマンドを保存しています。これは当時の出来事を記録するもので、権限変更コマンドは現行手順として古く危険です。アーカイブ内のコマンドを実行しないでください。
wiringPiSetup: Unable to open /dev/mem or /dev/gpiomem: Permission denied.
Aborting your program because if it can not access the GPIO
hardware then it most certianly won’t work
Try running with sudo?
sudo usermod -a -G gpio user_name
% change the owner and group respectively
sudo chown root.gpio /dev/gpiomem
sudo chmod g+rw /dev/gpiomem
If the problem is still unsolved, try to deactivate your virtual enviroment if used. Otherwise, try to use
sudo chown root.gpio /dev/mem && sudo chmod g+rw /dev/mem
This both two commands have the same to do with each other.
sudo usermod -a -G target_group user_name
sudo adduser user_name target_group