インストールガイド

様々な環境で Peeka をインストールして設定するためのガイドです。

目次

1. システム要件
   1. 基本要件
   2. Python バージョン比較
2. インストール方法
   1. pip でインストール（推奨）
      1. ベーシックバージョン（CLI のみ）
      2. フルバージョン（TUI 含む）
   2. uv でインストール
   3. ソースコードからインストール
3. Python < 3.14 の追加設定
   1. Debian/Ubuntu
   2. RHEL/CentOS/Fedora
   3. macOS
4. 権限設定
   1. Linux システム
      1. 一時的に ptrace 制限を緩和（テスト用）
      2. 永続的設定（本番環境推奨）
      3. SELinux システム（Fedora/RHEL）
   2. Docker コンテナ
5. インストールの確認
   1. バージョン確認
   2. テスト実行
   3. 依存関係の確認
6. よくある問題
   1. アタッチ失敗：権限がない
   2. Linux、Python < 3.14：デバッグシンボルが見つからない
   3. GDB のバージョンが古い
   4. macOS: LLDB が利用できない、または権限不足
7. 次のステップ
8. ヘルプの取得

---

システム要件

基本要件

• Python バージョン: Python 3.8.1 以上
• OS: Linux（推奨）、macOS
• 権限: ターゲットプロセスにアタッチする権限が必要（同じ UID または CAP_SYS_PTRACE）

Python バージョン比較

Python バージョン	アタッチメカニズム	追加要件
3.14+	PEP 768 sys.remote_exec	なし
3.8.1-3.13	Linux: GDB + ptrace、macOS: LLDB + dlopen	Linux: GDB 7.3+、python3-dbg、CAP_SYS_PTRACE、macOS: Xcode Command Line Tools

---

インストール方法

pip でインストール（推奨）

ベーシックバージョン（CLI のみ）

pip install peeka

フルバージョン（TUI 含む）

pip install peeka[tui]

uv でインストール

# ベーシックバージョン
uv pip install peeka

# フルバージョン（TUI 含む）
uv pip install "peeka[tui]"

# 開発環境（ソースコードから）
uv sync --dev

ソースコードからインストール

# リポジトリをクローン
git clone https://github.com/peeka-project/peeka.git
cd peeka

# インストール（ベーシックバージョン）
uv pip install -e .

# インストール（TUI 含む）
uv pip install -e ".[tui]"

# 開発環境（全依存関係）
uv sync --dev

---

Python < 3.14 の追加設定

Python 3.8.1-3.13 では、Linux は GDB と Python デバッグシンボル、macOS は LLDB と Xcode Command Line Tools が必要です。

Debian/Ubuntu

sudo apt-get update
sudo apt-get install gdb python3-dbg

RHEL/CentOS/Fedora

sudo yum install gdb python3-debuginfo

macOS

xcode-select --install

---

権限設定

Linux システム

一時的に ptrace 制限を緩和（テスト用）

echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope

永続的設定（本番環境推奨）

/etc/sysctl.d/10-ptrace.conf を編集：

kernel.yama.ptrace_scope = 1

設定を適用：

sudo sysctl -p /etc/sysctl.d/10-ptrace.conf

SELinux システム（Fedora/RHEL）

# SELinux の状態を確認
getenforce

# 一時的に ptrace を許可
sudo setsebool -P deny_ptrace off

# または特定のプロセス用に SELinux ポリシーを作成

Docker コンテナ

Docker コンテナを起動するときに --cap-add=SYS_PTRACE パラメータを追加：

docker run --cap-add=SYS_PTRACE your-image

docker-compose.yml で設定する場合：

services:
  app:
    image: your-image
    cap_add:
      - SYS_PTRACE
    security_opt:
      - seccomp=unconfined

---

インストールの確認

バージョン確認

peeka-cli --version
# peeka-cli 0.1.10

テスト実行

# デモアプリケーションを起動
python -m peeka.examples.demo --mode loop

# 別のターミナルでアタッチをテスト
peeka-cli attach <pid>

依存関係の確認

# Python バージョンを確認
python --version

# GDB の確認（Linux、Python < 3.14）
gdb --version

# LLDB の確認（macOS、Python < 3.14）
lldb --version

# Python デバッグシンボルの確認（Linux、Python < 3.14）
python -c "import sys; print(hasattr(sys, 'gettotalrefcount'))"

---

よくある問題

アタッチ失敗：権限がない

エラーメッセージ:

Error: Operation not permitted

解決策:

1. ターゲットプロセスと同じ UID を使用するか、sudo を使用することを確認
2. ptrace_scope の設定を確認
3. Docker の場合は CAP_SYS_PTRACE が追加されていることを確認

Linux、Python < 3.14：デバッグシンボルが見つからない

エラーメッセージ:

Error: Python debugging symbols not found

解決策:

# Debian/Ubuntu
sudo apt-get install python3-dbg

# RHEL/CentOS
sudo yum install python3-debuginfo

GDB のバージョンが古い

エラーメッセージ:

Error: GDB version 7.3+ required

解決策:

# GDB を更新
sudo apt-get update
sudo apt-get install --only-upgrade gdb

# またはソースから最新バージョンをコンパイル

macOS: LLDB が利用できない、または権限不足

エラーメッセージ:

Error: LLDB not found
Error: LLDB attach failed: permission denied

解決方法: Xcode Command Line Tools をインストールしてください：

xcode-select --install

---

次のステップ

インストールが完了したら、以下をご覧ください：

• クイックスタート - 基本的な使い方を学ぶ
• コマンドリファレンス - 使用可能なすべてのコマンドを確認
• サンプルチュートリアル - 実際のユースケース

---

ヘルプの取得

インストール中に問題が発生した場合：

1. トラブルシューティング を確認
2. GitHub Issues で質問