この記事の要点

基本: pip install パッケージ名。バージョン指定は ==（厳密）/ >=（以上）/ ~=（互換） requirements.txt: pip install -r requirements.txt でまとめてインストール、pip freeze > requirements.txt で固定化 仮想環境必須: python -m venv .venv + source .venv/bin/activate でプロジェクト隔離 Wheel（.whl）はビルド済バイナリ → 高速。sdist（.tar.gz）はソース配布、setup.py ビルドが必要 pip vs pipx vs poetry vs uv: CLI ツールは pipx、依存管理は poetry、爆速は uv。最近の標準は uv

pip とは

pip は Python 標準のパッケージインストーラーです。PyPI（Python Package Index）から .whl / .tar.gz を取得し、Python の site-packages に展開します。Python 3.4 以降は標準同梱（python -m pip）。

基本のインストール

# 最新版を入れる
pip install requests

# バージョン指定
pip install requests==2.31.0     # 厳密
pip install "requests>=2.28"     # 以上
pip install "requests~=2.31.0"   # 互換（2.31.x 系の最新、2.32 は入らない）
pip install "requests<3"         # 3 未満

# 複数パッケージ
pip install requests pandas numpy

# アップグレード
pip install --upgrade requests
pip install -U requests

# 特定の Python に対して
python3.11 -m pip install requests

# ユーザディレクトリにインストール（仮想環境外）
pip install --user requests
# → ~/.local/lib/python3.11/site-packages/ に入る

仮想環境（venv）と組み合わせる

システムの Python に直接入れると、プロジェクト間でバージョン衝突します。仮想環境を必ず作りましょう:

# プロジェクトディレクトリで仮想環境作成
python -m venv .venv

# 有効化（Linux/Mac）
source .venv/bin/activate

# 有効化（Windows PowerShell）
.venv\Scripts\Activate.ps1

# プロンプトに (.venv) と表示される
(.venv) $ pip install requests

# 仮想環境から抜ける
deactivate

# .venv をリポジトリにコミットしない（.gitignore に追加）
echo ".venv/" >> .gitignore

requirements.txt 運用

# 1. 現在の環境のパッケージとバージョンを書き出し
pip freeze > requirements.txt

# 中身の例:
# requests==2.31.0
# urllib3==2.0.7
# certifi==2023.7.22

# 2. 別の環境で復元
pip install -r requirements.txt

# 3. アップグレード可能な範囲で指定したい場合は
#    手書きで >= / ~= を使う
# requirements.in:
#   requests>=2.28
#   pandas~=2.0
# → pip-tools の pip-compile で requirements.txt 生成

requirements の分割

requirements/
  base.txt    # アプリ実行に必要
  dev.txt     # 開発用（pytest, black ...） -r base.txt を先頭に
  prod.txt    # 本番用（gunicorn ...）       -r base.txt を先頭に

# base.txt
django>=4.2,<5.0
psycopg2-binary

# dev.txt
-r base.txt
pytest
pytest-django
black
flake8

# 利用
pip install -r requirements/dev.txt

主なフラグ

フラグ	意味
--upgrade / -U	既存をアップグレード
--user	ユーザディレクトリにインストール
--no-deps	依存パッケージを入れない
--editable / -e	ローカルパッケージを開発インストール（symlink）
--target /path	指定ディレクトリに展開
--index-url URL	プライベートリポジトリ指定
--extra-index-url URL	追加のリポジトリ
--no-cache-dir	キャッシュを使わない
--pre	プレリリース版を含める
--dry-run	実行せず何が起きるか表示

確認系コマンド

# インストール済一覧
pip list
pip list --outdated   # アップグレード可能を表示
pip list --user
pip list --format=json

# 特定パッケージの詳細
pip show requests
# Name: requests
# Version: 2.31.0
# Location: .../site-packages
# Requires: charset-normalizer, idna, urllib3, certifi
# Required-by: ...

# 依存ツリー（要 pipdeptree）
pip install pipdeptree
pipdeptree
pipdeptree -p requests

# 何が壊れているか
pip check

アンインストール

# 1 個ずつ
pip uninstall requests
pip uninstall -y requests          # 確認スキップ

# requirements に書かれたものを一括削除
pip uninstall -r requirements.txt -y

# 全部消す（仮想環境を再構築する場合）
pip freeze | xargs pip uninstall -y

editable インストール（-e）

自作パッケージを開発中、ソース変更を逐次反映したい場合:

# プロジェクトディレクトリで
pip install -e .

# Git リポジトリから直接
pip install -e "git+https://github.com/user/repo.git@main#egg=mypkg"

# 開発依存込みで（extras_require）
pip install -e ".[dev]"

Wheel と sdist

PyPI のパッケージは Wheel (.whl) または sdist (.tar.gz) 形式:

形式	特徴
Wheel (.whl)	ビルド済バイナリ。インストールが速い。OS / Python ABI / アーキ別
sdist (.tar.gz)	ソース配布。setup.py / pyproject.toml でビルドしてからインストール

Wheel が無い OS / Python では sdist が落ちてきて、C コンパイラなどが必要になります（例: psycopg2 はソースビルドで libpq-dev 必須）。PEP 517 / 518 準拠のパッケージは pyproject.toml で build-system.requires を宣言、pip が分離環境で自動ビルドします。

キャッシュ管理

# キャッシュ場所
pip cache dir
# ~/.cache/pip （Linux）/ ~/Library/Caches/pip （Mac）

# サイズ確認
pip cache info

# 削除
pip cache purge

# キャッシュ無視
pip install --no-cache-dir requests

pip vs pipx vs poetry vs uv

ツール	用途	特徴
pip	パッケージ追加 / 削除	標準。requirements.txt 運用
pipx	CLI ツールを隔離インストール	black / poetry 等を入れる
poetry	依存管理 + パッケージ公開	pyproject.toml + poetry.lock
uv	pip / venv / pip-tools 統合の高速版	Rust 実装で 10〜100 倍速。2025 年以降の事実上標準

uv の例

# 導入
curl -LsSf https://astral.sh/uv/install.sh | sh

# 仮想環境 + パッケージ追加
uv venv .venv
source .venv/bin/activate
uv pip install requests

# プロジェクト管理
uv init myproject
cd myproject
uv add requests pandas
uv sync       # uv.lock に従って復元
uv run app.py

トラブルシューティング

症状	対処
SSL 証明書エラー	OS の CA 更新 / --trusted-host pypi.org（非推奨）
Could not find a version	Python バージョン互換性 / プレリリースは --pre
building wheel for X failed	OS 開発パッケージ（gcc, libpq-dev）追加
ModuleNotFoundError 後でも	venv をアクティブにしているか / which python 確認
pip 自体が古い	python -m pip install --upgrade pip

FAQ

Q: sudo pip install するな、と言われる
A: システム Python が壊れる原因に。pip install --user か仮想環境を使う。Debian/Ubuntu の Python 3.11+ は externally-managed-environment でブロックされる。

Q: requirements.txt と pyproject.toml どちら？
A: 既存プロジェクトはそのままで OK。新規なら pyproject.toml + uv or poetry を推奨。requirements.txt は CI / Docker のシンプルな復元用に残すケースも多い。

Q: ロックファイルが必要？
A: 本番再現性のために必須。pip freeze、poetry.lock、uv.lock、pip-tools の requirements.txt（pinned）など。