2026年8月20日

Pythonのpipでパッケージを管理する方法｜インストール・バージョン固定・requirements.txt・エラー対処

Linux基礎・コマンド

pipは、Pythonのライブラリ（パッケージ）をPyPIからインストール・更新・削除するための標準ツールです。基本は「仮想環境の中で」「python -m pip の形で」使い、入れたパッケージとバージョンを requirements.txt に書き出して、別の環境でも同じ状態を再現できるようにします。この記事では、よく使うコマンド、バージョン指定の書き方、requirements.txtの運用、依存関係の衝突や externally-managed-environment などのエラーへの対処、安全にパッケージを入れるための注意点までを説明します。

仮想環境（venv）の作り方とPython本体のインストールは、別記事で扱っています。この記事は、仮想環境ができている前提でpipの使い方に絞ります。

pipを使う前の2つの約束

仮想環境の中で使う

OSに入っているPythonに直接パッケージを入れると、OSのツールが使うライブラリのバージョンを変えてしまうことがあります。最近のUbuntuやDebianでは、これを防ぐために、仮想環境の外での pip install が externally-managed-environment というエラーで止められます。プロジェクトごとに仮想環境を作り、その中で使ってください。sudo pip install も避けます。

`pip` ではなく `python -m pip` と書く

PCやサーバーに複数のPythonがあると、pip コマンドが別のPythonにつながっていることがあります。python -m pip と書けば、今使っている python に対応するpipが動くため、「入れたはずなのに ModuleNotFoundError になる」という取り違えを防げます。

python -m pip --version
# pip 2x.x from /home/user/project/.venv/lib/python3.x/site-packages/pip (python 3.x)

表示されるパスが仮想環境の中を指していることを確認します。pip自体も定期的に更新されるので、仮想環境を作ったら最初に更新しておくと、新しい形式のパッケージを入れるときのエラーが減ります。

python -m pip install --upgrade pip

よく使うコマンド

# インストール
python -m pip install requests

# 更新
python -m pip install --upgrade requests

# 削除
python -m pip uninstall requests

# 入っているパッケージの一覧
python -m pip list

# 新しいバージョンがあるものだけ表示
python -m pip list --outdated

# パッケージの詳細（バージョン、依存先、依存元）
python -m pip show requests

# 依存関係に矛盾が無いか確認
python -m pip check

pip uninstall は指定したパッケージだけを削除し、一緒に入った依存パッケージは残ります。きれいにしたい場合は、仮想環境ごと作り直してrequirements.txtから入れ直すほうが手早く確実です。

pip show の出力にある Requires はそのパッケージが必要とするもの、Required-by はそのパッケージを必要としているものです。削除や更新の前に、影響する範囲を確認できます。

バージョンの指定方法

インストール時にバージョンの条件を付けられます。シェルが > や < をリダイレクトとして解釈しないよう、条件を含む指定は引用符で囲みます。

# ちょうどこのバージョン
python -m pip install "requests==2.32.3"

# 2.31以上、3未満
python -m pip install "requests>=2.31,<3"

# 互換リリース（2.32以上、3.0未満と同じ意味）
python -m pip install "requests~=2.32"

上のバージョン番号は書き方の例です。実際には、PyPIのパッケージページや変更履歴で、使いたいバージョンと対応するPythonのバージョンを確認してください。

アプリケーションでは、動作確認したバージョンを == で固定するのが一般的です。メジャーバージョン（先頭の数字）が上がると、使い方が変わる変更が入ることが多いためです。

requirements.txtで環境を再現する

書き出しと読み込み

今の仮想環境に入っているパッケージとバージョンは、pip freeze で書き出せます。

python -m pip freeze > requirements.txt

別のPCやサーバーでは、新しい仮想環境を作ってから読み込みます。

python -m pip install -r requirements.txt

freezeの注意点

pip freeze は、自分で入れたパッケージだけでなく、依存関係で自動的に入ったものもすべて書き出します。どれが直接使っているものか分かりにくくなるため、運用では次のように2つのファイルに分ける方法がよく使われます。

requirements.in … 自分が直接使うパッケージだけを書く（例: requests、pandas>=2）
requirements.txt … そこから依存関係まで含めて解決し、全部のバージョンを固定したもの

この変換には、pip-toolsの pip-compile などのツールを使えます。

python -m pip install pip-tools
pip-compile requirements.in      # requirements.txt が生成される
pip-sync requirements.txt        # 仮想環境をファイルの内容に合わせる

開発時だけ使うツール（テストやコード整形）は requirements-dev.txt に分け、本番サーバーには入れないようにすると、サーバーの構成が小さく保てます。

pyproject.tomlとの関係

自分のコードをパッケージとして配布する場合や、新しいプロジェクトでは、依存関係を pyproject.toml の dependencies に書く方法が標準になっています。この場合は、プロジェクトのフォルダで python -m pip install -e . を実行すると、自分のコードを編集可能な状態で入れ、依存パッケージも一緒に入ります。requirements.txtはアプリケーションの環境を固定する用途で併用されることが多いです。

依存関係の衝突を解決する

インストール時に次のようなメッセージが出ることがあります。

ERROR: pip's dependency resolver does not currently take into account all the packages that are installed. ...
package-a 1.0 requires library-x<2.0, but you have library-x 2.1 which is incompatible.

これは「パッケージAはライブラリXの2.0未満を必要としているのに、2.1が入っている」という意味です。次の順で確認します。

python -m pip show library-x で、どのパッケージがXを必要としているか（Required-by）を確認する
パッケージAの新しいバージョンがXの2.x系に対応していないか、変更履歴を確認し、対応していればAを更新する
対応していなければ、"library-x<2.0" のようにXのバージョンを下げて入れ直す
解決が難しい場合は、仮想環境を作り直し、requirements.inから入れ直す

複数のプロジェクトでこの問題がぶつかり合わないように分けることが、仮想環境を使う大きな理由でもあります。

よくあるエラーと対処

**error: externally-managed-environment**仮想環境の外でOSのPythonにインストールしようとしています。仮想環境を作って有効化するか、.venv/bin/python -m pip のように仮想環境のPythonを指定します。エラーを無視するオプション（--break-system-packages）もありますが、OSのツールが壊れるおそれがあるため使わないでください。

**ERROR: No matching distribution found for ...**パッケージ名の綴りが違うか、今のPythonのバージョンに対応したバージョンが公開されていません。PyPIでパッケージ名と対応するPythonのバージョンを確認します。新しいPythonが出た直後は、対応版がまだ公開されていないこともあります。

**ビルドに失敗する（Failed building wheel など）**そのパッケージの、今の環境向けのビルド済みファイル（wheel）が提供されておらず、手元でのコンパイルに失敗しています。まずpipを更新して、ビルド済みファイルが見つかるか試します。それでも失敗する場合は、エラーメッセージに表示される不足ファイルを手がかりに、コンパイラーや開発用のヘッダー（Ubuntuなら build-essential や python3-dev など）を入れます。

社内ネットワークで接続エラーやSSLエラーになるプロキシ経由でしか外部に出られない環境では、--proxy オプションや、pipの設定ファイルでプロキシを指定します。SSLの検証を無効にする --trusted-host を安易に付けると、通信の改ざんに気づけなくなるため、社内のネットワーク管理者に正しい証明書の設定方法を確認してください。

安全にパッケージを入れるための注意点

PyPIには誰でもパッケージを公開できるため、有名なパッケージに似た名前の不正なパッケージが見つかることがあります。

インストールする前に、パッケージ名の綴りと、PyPIのページにある公式リポジトリへのリンクを確認する
記事やチャットに貼られたコマンドをそのまま実行しない
pip-audit（Pythonのパッケージ管理を担うPyPAが公開しているツール）で、既知の脆弱性があるバージョンを使っていないか定期的に確認する
本番環境では、pip install --require-hashes -r requirements.txt のようにハッシュ値を照合する方法も検討する

コマンドラインで使うツール（例: コード整形ツールやHTTPクライアント）を単体で入れたいだけなら、pipxを使うと、ツールごとに専用の仮想環境が作られて、ほかのプロジェクトに影響しません。

pip以外にも、高速なuvや、依存関係とパッケージングをまとめて扱うPoetryなどのツールがあります。機能や推奨される使い方は頻繁に更新されているため、導入する場合は各ツールの公式ドキュメントを確認してください（2026年10月現在）。

まとめ

pipは仮想環境の中で、python -m pip の形で使う。sudo pip install は避ける
install・uninstall・list --outdated・show・check で日常の管理ができる
アプリケーションでは動作確認したバージョンを == で固定し、requirements.txt で環境を再現する
直接使うパッケージと依存先を分けたいなら、requirements.inとpip-compileを使う
依存関係の衝突は pip show の Required-by で原因を追い、更新か固定で解決する
インストール前にパッケージ名を確認し、pip-audit で脆弱性を定期的に調べる