pipコマンド一覧｜installのバージョン指定とrequirements.txt

pipとは、Pythonのパッケージ（ライブラリ）をPyPIなどから取得して、インストール・更新・削除・一覧表示を行う公式のコマンドです。 pip install パッケージ名 だけでも使えますが、バージョンを指定する書き方、requirements.txt で環境を再現する手順、エラーが出たときの読み方まで知っておくと、環境づくりで迷う時間がぐっと減ります。

この記事では、pip のコマンドを一覧表にまとめ、バージョン指定の演算子、requirements.txt・constraints・ハッシュ検証、そして externally-managed-environment（PEP 668）をはじめとするエラーの再現と対処を、すべて手元で実行した結果つきで紹介します。検証は Python 3.11.15 の venv 内で pip 26.2.1（2026年10月時点の最新）を使いました。PEP 668 の再現だけは Ubuntu 24.04 の Python 3.12 + pip 24.0 で行っています。出力中の長いパスは ... に省略しています。

pipコマンドの早見表

まずは「やりたいこと」から引ける一覧です。コマンドは python -m pip ... の形で書くと、どの Python に入るかがはっきりします（理由は後述）。venv を有効化している間は pip ... と短く書いても同じ結果になります。

やりたいこと	コマンド	補足
インストール	pip install requests	最新の安定版が入る
バージョンを固定して入れる	pip install "requests==2.31.0"	演算子は引用符で囲む
範囲を指定して入れる	pip install "requests>=2.32,<2.33"	カンマは「かつ」
最新へ更新	pip install -U requests	-U は --upgrade
追加機能つきで入れる	pip install "requests[socks]"	extras（オプション依存）
一括インストール	pip install -r requirements.txt	環境の復元
上限つきで一括インストール	pip install -r req.in -c constraints.txt	constraints は「入れるなら、この版」
ハッシュを検証して入れる	pip install --require-hashes -r req.txt	改ざん検知
開発中の自作パッケージを入れる	pip install -e .	編集可能インストール
何が入るかだけ確認	pip install --dry-run flask	実際には入れない
アンインストール	pip uninstall requests	-y で確認を省略
一覧を表示	pip list	--outdated で更新可能なもの
詳細を表示	pip show requests	依存先・場所・-f でファイル一覧
固定形式で書き出す	pip freeze > requirements.txt	名前==版 形式
依存の整合を点検	pip check	食い違いがあれば終了コード 1
公開されている版を調べる	pip index versions requests	インストール済み・最新も表示
ファイルだけ取得	pip download six -d dl	オフライン配布用
キャッシュの確認・削除	pip cache info / pip cache purge	場所は pip cache dir
設定の確認・変更	pip config list / pip config set	pip.conf を編集
環境を JSON で出力	pip inspect	機械処理向け
ロックファイル生成	pip lock -r req.in -o pylock.toml	pip 25.1 以降。実験的機能
pip 自体を更新	python -m pip install -U pip	この形が公式の手順
バージョン確認	python -m pip --version	どの Python の pip かも分かる

準備：venv を作って最新の pip にする

pip を試すときは、仮想環境（venv）の中で行うのが基本です。OS が管理する Python にそのまま入れようとすると、後述の PEP 668 のエラーで止まる環境が増えています。venv の作り方や有効化のコマンドは別記事「Python venvの使い方」で OS 別にまとめているので、ここでは最短の手順だけ載せます。

python3 -m venv .venv
source .venv/bin/activate        # Windows は .venv\Scripts\activate
python -m pip install -U pip
python -m pip --version

実行結果：

Successfully installed pip-26.2.1
pip 26.2.1 from .../.venv/lib/python3.11/site-packages/pip (python 3.11)

pip help で表示されるコマンドは、pip 26.2.1 では次の 18 個でした。

install / lock / download / uninstall / freeze / inspect / list / show / check /
config / search / cache / index / wheel / hash / completion / debug / help

search は一覧に残っていますが、PyPI 側が検索用の API を提供していないため、PyPI に対しては使えません（公式ドキュメントで確認）。パッケージを探すときは pypi.org のサイト検索、版を調べるときは pip index versions を使います。

python -m pip を使う理由

pip と python -m pip は同じ処理をしますが、python -m pip は「その python に入れる」ことが確実です。pip という名前のコマンドは PATH の順番で決まるため、複数の Python がある環境では、思っていたのとは別の Python に入ることがあります。

手元でも、venv を抜けた状態で確認すると、Python ごとに別の pip が動いていました。

python -m pip --version            # venv 有効時
deactivate
python3 -m pip --version           # OS の Python 3.11
/usr/bin/python3.12 -m pip --version

pip 26.2.1 from .../.venv/lib/python3.11/site-packages/pip (python 3.11)
pip 24.0 from /usr/lib/python3/dist-packages/pip (python 3.11)
pip 24.0 from /usr/lib/python3/dist-packages/pip (python 3.12)

書き方	入る先	向いている場面
pip install ...	PATH で最初に見つかった pip の Python	venv を有効化しているとき
python -m pip install ...	その python 自身	いつでも。手順書やスクリプトに書くとき
py -3.12 -m pip install ...	Windows で版を選んだ Python	Windows で複数版があるとき

「インストールしたのに ModuleNotFoundError になる」ときの多くは、この入れ先のずれが原因です。python -m pip --version の末尾のパスと、スクリプトを動かす python が同じかを見ると、すぐに切り分けられます。

pip install の使い方とバージョン指定

バージョン指定演算子の一覧

バージョンの条件は、PEP 440 で決められた演算子で書きます。< や > はシェルのリダイレクトと解釈されるので、必ず引用符で囲みます。

演算子	意味	例	入る範囲
==	完全一致	"requests==2.31.0"	2.31.0 だけ
>=	以上	"requests>=2.32"	2.32 以上の最新
<=	以下	"requests<=2.31.0"	2.31.0 以下の最新
< / >	未満 / より大きい	"requests<2.33"	2.33 を含まない
!=	その版を除く	"idna!=3.10"	3.10 以外
~=	互換リリース	"urllib3~=2.2.0"	2.2.0 以上 2.3 未満
== とワイルドカード	前方一致	"urllib3==2.2.*"	2.2 系
カンマ	条件を「かつ」でつなぐ	"requests>=2.32,<2.33"	両方を満たす版
[extra]	追加の依存も入れる	"requests[socks]"	本体 + PySocks
@ URL	URL・Git から直接	"mylib @ git+https://example.com/mylib.git@v1.0"	指定した場所

~=（互換リリース）は、最後の桁だけを動かしてよいという意味です。~=2.2.0 は「2.2.0 以上、2.3 未満」、~=2.2 は「2.2 以上、3.0 未満」になります。桁数で範囲が変わる点を押さえておくと、狙いどおりに書けます。

実行して確かめる

順番に実行し、それぞれ何が入ったかを確認しました。

pip install "requests==2.31.0"
pip install "requests>=2.32,<2.33"
pip install "urllib3~=2.2.0"
pip install "idna!=3.10,<3.11"
pip install -U requests

実行結果（各コマンドの最終行）：

Successfully installed certifi-2026.7.22 charset-normalizer-3.5.2 idna-3.20 requests-2.31.0 urllib3-2.8.0
Successfully installed requests-2.32.5
Successfully installed urllib3-2.2.3
Successfully installed idna-3.9
Successfully installed requests-2.34.2

読み取れることを表にまとめます。

コマンド	結果	わかること
"requests==2.31.0"	requests 2.31.0 と依存 4 つ	依存パッケージも一緒に入る
"requests>=2.32,<2.33"	2.32.5	範囲内でいちばん新しい版が選ばれる
"urllib3~=2.2.0"	2.8.0 から 2.2.3 へ	2.2 系の最新。すでに入っている版は入れ替わる
"idna!=3.10,<3.11"	3.9	3.10 を除いた、3.11 未満の最新
-U requests	2.34.2	条件なしの -U は最新の安定版へ

すでに入っているパッケージに対して、条件なしの pip install requests を実行しても更新はされません（Requirement already satisfied と表示されます）。更新したいときは -U を付けるか、版を明示します。

extras（追加の依存）を入れる

パッケージ名[名前] と書くと、そのパッケージが用意しているオプションの依存も入ります。

pip install "requests[socks]"

Installing collected packages: PySocks
Successfully installed PySocks-1.7.1

複数指定は "パッケージ[a,b]"、バージョン指定と組み合わせるときは "requests[socks]>=2.32" の順に書きます。

よく使う install のオプション

オプション	働き	使う場面
-U / --upgrade	条件を満たす最新へ更新	版を上げたいとき
-r ファイル	ファイルに書かれたものを一括で入れる	環境の復元
-c ファイル	constraints（版の制約）を適用	依存の版をそろえる
-e パス	編集可能インストール	自作パッケージの開発
--dry-run	入るものを表示するだけ	影響を事前に見る
--no-deps	依存を入れない	依存を別管理しているとき
--pre	プレリリース版も候補にする	rc・beta を試すとき
--force-reinstall	入っていても入れ直す	壊れたファイルを戻すとき
--no-cache-dir	キャッシュを使わない	コンテナのイメージを小さくするとき
--user	ユーザー用の場所に入れる	venv を使わず管理者権限もないとき
-i URL / --index-url	取得元を切り替える	社内のパッケージサーバーを使うとき
--no-index --find-links dir	フォルダ内のファイルだけで入れる	オフライン環境
--require-hashes	ハッシュを必ず検証	再現性と改ざん検知

--dry-run は、入れる前に影響範囲を見たいときに便利です。

pip install --dry-run flask

Would install Flask-3.1.3 Jinja2-3.1.6 MarkupSafe-3.0.3 Werkzeug-3.1.9 blinker-1.9.0 click-8.5.0 itsdangerous-2.2.0

インストール済みパッケージを調べる

pip list：一覧を見る

pip list

Package            Version
------------------ ---------
certifi            2026.7.22
charset-normalizer 3.5.2
idna               3.20
pip                26.2.1
requests           2.31.0
setuptools         79.0.1
urllib3            2.8.0

オプション	表示されるもの
pip list --outdated（-o）	新しい版が公開されているもの
pip list --not-required	ほかのパッケージから依存されていないもの（自分で入れたものの目安）
pip list --format=json	JSON 形式
pip list -e	編集可能インストールだけ

--outdated の実行結果です。現在の版・最新版が並ぶので、更新の計画を立てやすくなります。

Package    Version Latest Type
---------- ------- ------ -----
idna       3.9     3.20   wheel
setuptools 79.0.1  84.0.0 wheel
urllib3    2.2.3   2.8.0  wheel

pip show：1 つのパッケージを詳しく見る

pip show requests

Name: requests
Version: 2.31.0
Summary: Python HTTP for Humans.
Home-page: https://requests.readthedocs.io
Author: Kenneth Reitz
Author-email: me@kennethreitz.org
License: Apache 2.0
Location: .../.venv/lib/python3.11/site-packages
Requires: certifi, charset-normalizer, idna, urllib3
Required-by: 

Requires は「このパッケージが必要とするもの」、Required-by は「このパッケージを必要としているもの」です。アンインストールしてよいか迷ったら Required-by が空かどうかを見ます。Location は入っている場所で、入れ先のずれを調べるときにも役立ちます。入っていない名前を指定すると WARNING: Package(s) not found: six と表示されます。

pip index versions：公開されている版を調べる

pip index versions requests

requests (2.34.2)
Available versions: 2.34.2, 2.34.1, 2.34.0, 2.33.1, 2.33.0, 2.32.5, 2.32.4, 2.32.3, 2.32.2, 2.31.0, ...
  INSTALLED: 2.31.0
  LATEST:    2.34.2

「どの版が指定できるのか」を、インストールせずに確認できます。== で固定する版を決める前に実行すると確実です。

pip check：依存の食い違いを点検する

pip check

No broken requirements found.

わざと依存を無視して入れた（--no-deps で urllib3 1.25.11 を入れた）状態では、次のように食い違いが報告され、終了コードは 1 になりました。

requests 2.34.2 has requirement urllib3<3,>=1.26, but you have urllib3 1.25.11.

CI の中で pip check を 1 行入れておくと、依存の食い違いを早い段階で見つけられます。

pip inspect：環境を JSON で出力する

pip inspect は、インストール済みパッケージのメタデータを JSON で出力します。手元ではトップレベルのキーが version・pip_version・installed・environment の 4 つで、installed の各要素には metadata・metadata_location・installer・requested が入っていました。requested が true のものは「自分で指定して入れたもの」、false は「依存として入ったもの」です。

pip inspect > env.json

人が読むなら pip list、プログラムで処理するなら pip inspect と使い分けます。

pip uninstall：パッケージを削除する

pip uninstall -y PySocks

Found existing installation: PySocks 1.7.1
Uninstalling PySocks-1.7.1:
  Successfully uninstalled PySocks-1.7.1

やりたいこと	コマンド
確認なしで削除	pip uninstall -y パッケージ名
複数まとめて削除	pip uninstall -y a b c
requirements.txt に書かれたものを削除	pip uninstall -y -r requirements.txt

pip uninstall は指定したパッケージだけを削除し、一緒に入った依存パッケージは残ります。 環境をまっさらに戻したいときは、venv のフォルダを削除して作り直すのがいちばん早く、確実です。

requirements.txt の作成から復元まで

requirements.txt は、入れるパッケージを 1 行に 1 つ書いたテキストファイルです。ファイル名は慣習で、pip は -r で渡されたファイルを読むだけです。

作成：pip freeze で書き出す

pip freeze > requirements.txt
cat requirements.txt

certifi==2026.7.22
charset-normalizer==3.5.2
idna==3.9
requests==2.34.2
urllib3==2.2.3

pip freeze は pip・setuptools などの基本ツールを除いて、名前==版 の形で出力します。pip list との違いは次のとおりです。

項目	pip list	pip freeze
形式	表	名前==版（requirements 形式）
pip・setuptools	表示する	表示しない（--all で表示）
主な用途	目で確認する	ファイルに書き出して復元に使う

復元：別の環境に同じ版を入れる

新しい venv を作り、書き出したファイルから復元しました。

python3 -m venv .venv2
.venv2/bin/python -m pip install -r requirements.txt

Successfully installed certifi-2026.7.22 charset-normalizer-3.5.2 idna-3.9 requests-2.34.2 urllib3-2.2.3

5 つすべてが同じ版で入りました。 これが「環境を再現する」基本の流れです。

requirements.txt に書ける内容

書き方	意味
requests==2.34.2	版を固定
requests>=2.32,<3	範囲を指定
requests[socks]	extras つき
# コメント	コメント行
-r base.txt	別のファイルを読み込む
-c constraints.txt	constraints を適用
-e ./mylib	編集可能インストール
--index-url https://example.com/simple	取得元を指定
pywin32; sys_platform == "win32"	条件つき（環境マーカー）
six==1.17.0 --hash=sha256:...	ハッシュつき

開発用と本番用を分けるときは、requirements-dev.txt の先頭に -r requirements.txt と書き、その下に pytest などの開発用ツールを足す形がよく使われます。

手書きと freeze の使い分け

方法	内容	向いている場面
手書き（直接使うものだけ）	requests>=2.32 のように、自分が import するものだけ	何を使っているかを読みやすく保ちたい
pip freeze	依存も含めた全部を == で固定	まったく同じ環境を再現したい
両方（req.in + 固定ファイル）	手書きを元に、固定ファイルを生成	読みやすさと再現性の両立

3 つ目の「元になるファイル + 固定ファイル」の考え方をそのまま道具にしたのが、pip lock、pip-tools、uv です。uv でのロックの流れは別記事「uvの使い方」で扱っています。

constraints.txt（-c）：入れるなら、この版

constraints ファイルは、「インストールはしないが、もし入るならこの版にする」 という制約だけを書くファイルです。requirements との違いを実行で確かめました。

printf 'requests\n' > req.in
printf 'urllib3==2.2.3\nidna==3.9\nsix==1.16.0\n' > constraints.txt
python -m pip install -r req.in -c constraints.txt
python -m pip freeze

Successfully installed certifi-2026.7.22 charset_normalizer-3.5.2 idna-3.9 requests-2.34.2 urllib3-2.2.3
certifi==2026.7.22
charset-normalizer==3.5.2
idna==3.9
requests==2.34.2
urllib3==2.2.3

requests の依存である urllib3 と idna は constraints の版になり、constraints に書いただけの six は入りませんでした。 複数のサービスで依存の版をそろえたいときや、特定の依存だけ版を抑えたいときに向いています。

ファイル	書かれたものは入るか	役割
requirements（-r）	入る	何を入れるか
constraints（-c）	入らない（必要になったときだけ版を縛る）	どの版にそろえるか

--require-hashes：ハッシュで中身を検証する

--hash を書いた requirements は、ダウンロードしたファイルのハッシュが一致したときだけインストールされます。まず pip download でファイルを取得し、pip hash で値を出します。

pip download six==1.17.0 --no-deps -d dl
pip hash dl/six-1.17.0-py2.py3-none-any.whl

Saved ./dl/six-1.17.0-py2.py3-none-any.whl
dl/six-1.17.0-py2.py3-none-any.whl:
--hash=sha256:4721f391ed90541fddacab5acf947aa0d3dc7d27b2e1e8eda2be8970586c3274

この値を requirements に書きます（req-hash.txt）。

six==1.17.0 \
    --hash=sha256:4721f391ed90541fddacab5acf947aa0d3dc7d27b2e1e8eda2be8970586c3274

pip install --require-hashes -r req-hash.txt

Successfully installed six-1.17.0

ハッシュをわざと 000...0 に書き換えると、次のように止まりました。

ERROR: THESE PACKAGES DO NOT MATCH THE HASHES FROM THE REQUIREMENTS FILE. If you have updated the package versions, please update the hashes. Otherwise, examine the package contents carefully; someone may have tampered with them.
    six==1.17.0 from https://files.pythonhosted.org/packages/.../six-1.17.0-py2.py3-none-any.whl (from -r req-bad.txt (line 1)):
        Expected sha256 0000000000000000000000000000000000000000000000000000000000000000
             Got        4721f391ed90541fddacab5acf947aa0d3dc7d27b2e1e8eda2be8970586c3274

また、ハッシュのない行が混ざっていると、次のメッセージで止まります。

ERROR: Hashes are required in --require-hashes mode, but they are missing from some requirements. Here is a list of those requirements along with the hashes their downloaded archives actually had. Add lines like these to your requirements files to prevent tampering. (If you did not enable --require-hashes manually, note that it turns on automatically when any package has a hash.)
    six==1.17.0 --hash=sha256:4721f391ed90541fddacab5acf947aa0d3dc7d27b2e1e8eda2be8970586c3274

押さえておきたい点は 3 つです。

• 1 行でも --hash があると、ハッシュ検証モードが自動で有効になる（メッセージにも書かれています）
• ハッシュ検証モードでは、すべてのパッケージを == で固定し、依存も含めて全行にハッシュが必要
• OS や Python の版ごとにファイル（wheel）が異なるパッケージは、対象のファイルの数だけ --hash を並べる

全行のハッシュを手で管理するのは手間がかかるので、生成は道具に任せるのが楽です。pip 25.1 以降の pip lock（実験的機能）は、ハッシュ入りの pylock.toml（PEP 751 の形式）を出力します。

pip lock -r req.in -o pylock.toml

pip download と pip cache：オフラインとキャッシュ

pip download：ファイルだけ取得する

pip download は、インストールせずに配布ファイルだけを保存します。取得したフォルダを別のマシンへ運び、--no-index --find-links で入れれば、ネットワークにつながらない環境でもインストールできます。

pip download six==1.17.0 --no-deps -d dl     # つながる環境で取得
pip install --no-index --find-links dl six    # 取得したフォルダだけで入れる

Successfully installed six-1.17.0

-r requirements.txt -d dl とすれば、依存も含めてまとめて取得できます。取得する側と入れる側で OS・Python の版が違うときは、--platform・--python-version・--only-binary=:all: で対象を指定します（この組み合わせは手元では実行しておらず、公式ドキュメントで確認した内容です）。

pip cache：キャッシュを確認・削除する

pip は、一度ダウンロードしたファイルをキャッシュに保存し、次回以降の取得を速くします。

pip cache dir
pip cache info

/root/.cache/pip
Locally built wheels location: /root/.cache/pip/wheels
Locally built wheels size: 2.4 MB
Number of locally built wheels: 2

コマンド	働き
pip cache dir	キャッシュの場所を表示
pip cache info	サイズと件数を表示
pip cache list	手元でビルドした wheel の一覧
pip cache remove 名前	指定したパッケージの wheel を削除
pip cache purge	すべて削除

ディスクの空きを増やしたいときは pip cache purge、Docker イメージに残したくないときは pip install --no-cache-dir を使います（purge と remove は共有環境のため手元では実行していません）。

pip config：設定を保存する

毎回同じオプションを付ける代わりに、設定ファイル（pip.conf、Windows は pip.ini）に保存できます。venv 専用の設定にする --site で試しました。

pip config --site set global.timeout 30
pip config list
pip config --site unset global.timeout

Writing to .../.venv/pip.conf
global.timeout='30'

書き込まれた .venv/pip.conf の中身は次のとおりです。

[global]
timeout = 30

範囲	オプション	ファイルの場所（Linux の例）
OS 全体	--global	/etc/pip.conf
ユーザー	--user（既定）	~/.config/pip/pip.conf
venv	--site	.venv/pip.conf

設定は、コマンドのオプション名から -- を取った名前で書きます（--index-url は global.index-url）。環境変数でも同じ設定ができ、PIP_ + 大文字のオプション名（PIP_INDEX_URL、PIP_NO_CACHE_DIR など）です。どのファイルが読まれているかは pip config debug で確認できます。優先順位は「コマンドのオプション > 環境変数 > 設定ファイル」です。

pip install -e：編集可能インストール

自作のパッケージを開発するときは、-e（editable）で入れると、ソースを書き換えた結果が再インストールなしで反映されます。 最小の構成で試しました。

mylib/
├── pyproject.toml
└── src/
    └── mylib/
        └── __init__.py

pyproject.toml：

[build-system]
requires = ["setuptools>=77"]
build-backend = "setuptools.build_meta"

[project]
name = "mylib"
version = "0.1.0"
requires-python = ">=3.10"
dependencies = ["idna>=3.7"]

[project.optional-dependencies]
dev = ["six"]

src/mylib/__init__.py：

def hello():
    return "hello v1"

cd mylib
pip install -e ".[dev]"
python -c "import mylib; print(mylib.hello(), mylib.__file__)"

Successfully installed mylib-0.1.0
hello v1 .../mylib/src/mylib/__init__.py

__file__ が site-packages ではなく、元のソースの場所を指しているのがポイントです。v1 を v2 に書き換えて、そのままもう一度実行すると：

hello v2

pip list には場所が表示され、pip freeze には -e の行として出力されます。

Package            Version   Editable project location
------------------ --------- -------------------------
mylib              0.1.0     .../mylib

# Editable install with no version control (mylib==0.1.0)
-e .../mylib

入れ方	ソースの変更	向いている場面
pip install .	入れ直すまで反映されない	配布物としての動作確認
pip install -e .	すぐ反映される	開発中

pyproject.toml の dependencies や名前・版を変えたときは、-e でも入れ直しが必要です。

よくあるエラーの再現と対処

実際に再現させたエラー文と、原因・対処をまとめます。

エラー文（一部）	主な原因	対処
error: externally-managed-environment	OS 管理の Python に直接入れようとした	venv を作る / pipx を使う
No matching distribution found	名前・版の指定違い、Python の版が対象外	pip index versions で確認
ResolutionImpossible	指定した版どうしが両立しない	範囲をゆるめる
CERTIFICATE_VERIFY_FAILED	通信経路の証明書を検証できない	--cert で証明書を渡す
[Errno 13] Permission denied	入れ先に書き込めない	venv を自分で作る
Can not perform a '--user' install	venv の中で --user を付けた	--user を外す

externally-managed-environment（PEP 668）

Ubuntu 23.04 以降、Debian 12 以降、Homebrew の Python などでは、OS が管理する Python に pip で直接インストールしようとすると、このエラーで止まります。Ubuntu 24.04 の Python 3.12 で再現しました。

/usr/bin/python3.12 -m pip install six

error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
    python3-xyz, where xyz is the package you are trying to
    install.

    If you wish to install a non-Debian-packaged Python package,
    create a virtual environment using python3 -m venv path/to/venv.
    Then use path/to/venv/bin/python and path/to/venv/bin/pip. Make
    sure you have python3-full installed.

    If you wish to install a non-Debian packaged Python application,
    it may be easiest to use pipx install xyz, which will manage a
    virtual environment for you. Make sure you have pipx installed.

note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this, at the risk of breaking your Python installation or OS, by passing --break-system-packages.
hint: See PEP 668 for the detailed specification.

これは不具合ではなく、OS のパッケージ管理（apt など）と pip が同じ場所を書き換えて、OS のツールが動かなくなるのを防ぐための仕組みです。目印は、標準ライブラリのフォルダに置かれた EXTERNALLY-MANAGED というファイルで、手元でも /usr/lib/python3.12/EXTERNALLY-MANAGED にありました。--user を付けても同じエラーになります。

やりたいこと	対処
開発用のライブラリを入れたい	python3 -m venv .venv で venv を作り、その中で pip install
コマンドとして使うツールを入れたい	pipx install ツール名 または uv tool install ツール名
OS 全体で使いたい	sudo apt install python3-パッケージ名
使い捨てのコンテナなど	--break-system-packages を付ける（影響を理解したうえで）

ほとんどの場合、venv を作るのが答えです。 --break-system-packages は、作り直しができるコンテナのような環境に限って使うと安心です。

No matching distribution found

存在しない版と、存在しない名前で再現しました。

pip install "requests==9.9.9"
pip install reqests-nonexistent-xyz

ERROR: Could not find a version that satisfies the requirement requests==9.9.9 (from versions: 0.2.0, 0.2.1, ..., 2.34.2)
ERROR: No matching distribution found for requests==9.9.9

ERROR: Could not find a version that satisfies the requirement reqests-nonexistent-xyz (from versions: none)
ERROR: No matching distribution found for reqests-nonexistent-xyz

from versions: の中身が手がかりです。 版が並んでいれば「名前は合っているが、その版がない」、none なら「名前が違う、または取得元に届いていない」と読めます。

もう 1 つ多いのが、Python の版が対象外のケースです。Python 3.11 で Django 6.0 を入れようとすると、理由がはっきり表示されました。

ERROR: Ignored the following versions that require a different python version: 6.0 Requires-Python >=3.12; 6.0.1 Requires-Python >=3.12; ...
ERROR: Could not find a version that satisfies the requirement django==6.0 (from versions: ...)
ERROR: No matching distribution found for django==6.0

from versions: の表示	考えられる原因	確認・対処
版が並ぶ	指定した版が存在しない	pip index versions 名前 で版を確認
none	名前のつづり違い	pypi.org で正式名を確認
none + SSL の警告	取得元に接続できていない	次項の SSL を確認
Requires-Python の行がある	Python の版が対象外	Python を上げる、または対応する版を指定

依存の競合（ResolutionImpossible）

両立しない版を同時に指定して再現しました。

pip install "requests==2.34.2" "urllib3==1.25.11"

ERROR: Cannot install requests==2.34.2 and urllib3==1.25.11 because these package versions have conflicting dependencies.

The conflict is caused by:
    The user requested urllib3==1.25.11
    requests 2.34.2 depends on urllib3<3 and >=1.26

To fix this you could try to:
1. loosen the range of package versions you've specified
2. remove package versions to allow pip to attempt to solve the dependency conflict

ERROR: ResolutionImpossible: for help visit https://pip.pypa.io/en/latest/topics/dependency-resolution/#dealing-with-dependency-conflicts

The conflict is caused by: の下に、ぶつかっている条件がそのまま書かれています。 この例では「自分は urllib3 1.25.11 を指定した」「requests 2.34.2 は urllib3 1.26 以上を求めている」の 2 行です。

対処	例
自分の指定をゆるめる	urllib3==1.25.11 を urllib3>=1.26,<3 に
片方の指定を外して pip に任せる	pip install "requests==2.34.2"
相手側の版を合わせる	urllib3 1.25 系に対応する requests の版を選ぶ
原因を追う	pip show パッケージ名 の Requires と Required-by を見る

--no-deps で依存を無視して入れることもできますが、その場合は pip check が食い違いを報告します。まずは条件をゆるめる方向で調整するのがおすすめです。

SSL: CERTIFICATE_VERIFY_FAILED

自己署名証明書のローカルサーバーを取得元に指定して再現しました。

WARNING: Retrying (Retry(total=0, connect=None, read=None, redirect=None, status=None)) after connection broken by 'SSLError(SSLCertVerificationError(1, '[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self-signed certificate (_ssl.c:1016)'))': /simple/six/
Could not fetch URL https://localhost:7550/simple/six/: There was a problem confirming the ssl certificate: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self-signed certificate (_ssl.c:1016) - skipping
ERROR: Could not find a version that satisfies the requirement six (from versions: none)
ERROR: No matching distribution found for six

最後の行は No matching distribution ですが、本当の原因はその上の SSL の行です。 エラーは下から読むだけでなく、WARNING の行までさかのぼると原因にたどり着けます。

社内ネットワークで通信を中継するプロキシが独自の証明書を使っている場合に、よく起こります。対処は次のとおりです（以下の設定は公式ドキュメントで確認した内容です。今回の検証環境自体も、環境変数 PIP_CERT で証明書を渡す構成でした）。

対処	コマンド・設定
証明書（CA バンドル）を渡す	pip install --cert /path/to/ca-bundle.crt パッケージ名
設定に保存する	pip config set global.cert /path/to/ca-bundle.crt
環境変数で渡す	PIP_CERT=/path/to/ca-bundle.crt
OS の証明書ストアを使う	pip install --use-feature=truststore パッケージ名
プロキシを指定する	pip install --proxy http://proxy.example.com:8080 パッケージ名

--trusted-host は証明書の検証を省略する指定です。検証を残したまま解決できる --cert を先に試すと、安全性を保てます。

Permission denied

root が作った venv に、一般ユーザーでインストールしようとして再現しました。

Installing collected packages: cowsay
ERROR: Could not install packages due to an OSError: [Errno 13] Permission denied: '/tmp/t155perm/lib/python3.11/site-packages/cowsay'
Check the permissions.

入れ先のフォルダに書き込む権限がない、というそのままの意味です。 sudo pip install で通すこともできますが、ファイルの所有者が入り混じり、あとで同じエラーが続く原因になります。

状況	対処
他のユーザーが作った venv	自分のユーザーで venv を作り直す
OS の Python に入れようとした	venv を作る（PEP 668 の項と同じ）
Windows で「アクセスが拒否されました」	そのパッケージを使っているプログラム（実行中の Python やエディタ）を終了してから再実行
以前 sudo で入れて所有者が root になった	venv を作り直すのが確実

--user インストールと venv

--user は、管理者権限がなくても書き込めるユーザー用の場所（Linux では ~/.local/lib/pythonX.Y/site-packages）に入れるオプションです。PEP 668 の対象ではない環境（手元の Python 3.11 + pip 24.0）で一般ユーザーが実行すると、--user を付けなくても自動で切り替わりました。

Defaulting to user installation because normal site-packages is not writeable
Installing collected packages: cowsay
  WARNING: The script cowsay is installed in '/home/t155u/.local/bin' which is not on PATH.
  Consider adding this directory to PATH or, if you prefer to suppress this warning, use --no-warn-script-location.
Successfully installed cowsay-6.1

pip show cowsay の Location は /home/t155u/.local/lib/python3.11/site-packages でした。場所は python3 -m site --user-site で確認できます。コマンドが見つからないときは、WARNING にあるとおり ~/.local/bin を PATH に加えます。

一方、venv の中で --user を付けると、次のエラーになります。

ERROR: Can not perform a '--user' install. User site-packages are not visible in this virtualenv.

venv はユーザー用の場所を参照しない作りなので、venv の中では --user を外すだけで解決します。

入れ先	コマンド	特徴
venv	python -m pip install 名前（venv 有効時）	フォルダごとに独立。いちばんおすすめ
ユーザー用	python3 -m pip install --user 名前	同じユーザーの全作業で共有される
OS 全体	sudo apt install python3-名前	OS のパッケージ管理に任せる

よくある質問

Q. pip と pip3 の違いは何ですか？ A. どちらも同じ pip で、結び付いている Python が異なる場合があるだけです。Python 2 と 3 が共存していた頃の名残で、pip3 は Python 3 用を指します。venv の中ではどちらも同じものです。迷ったら python -m pip と書くと、使う Python を自分で選べます。

Q. requirements.txt と pyproject.toml はどちらを使えばよいですか？ A. スクリプトやアプリの環境を再現するだけなら requirements.txt で十分です。パッケージとして配布する、pip install -e . で開発する、ツールの設定をまとめたい、といった場合は pyproject.toml の dependencies に書きます。両方を使い、pyproject.toml に「使うもの」、requirements.txt やロックファイルに「固定した版」を置く構成もよく使われます。

Q. インストール済みのパッケージをすべて最新にするコマンドはありますか？ A. pip には一括更新のコマンドはありません。pip list --outdated で対象を確認し、pip install -U 名前1 名前2 のように指定して更新します。requirements.txt の版を書き換えてから pip install -r requirements.txt を実行する流れにすると、変更が記録として残ります。

Q. pip と uv はどう使い分けますか？ A. pip は Python に標準で付いてくるため、追加の準備なしでどこでも使えます。uv は pip 互換のコマンド（uv pip install）に加えて、ロックファイルや Python 本体の管理までを高速に行えます。まず pip で仕組みを理解し、チームで再現性や速度を求める段階で uv を取り入れると、移行がスムーズです。

まとめ

• コマンドは python -m pip の形で書くと、どの Python に入るかがはっきりする
• バージョン指定は ==・>=・<・~=・!= をカンマでつなぎ、引用符で囲む。~=2.2.0 は 2.2 系の最新
• pip freeze > requirements.txt で書き出し、pip install -r requirements.txt で復元する
• constraints（-c）は「入れるなら、この版」。書いただけではインストールされない
• --require-hashes は全行に == とハッシュが必要。生成は pip lock などの道具に任せると楽
• externally-managed-environment（PEP 668）は venv を作れば解決。--user は venv の中では使えない
• エラーは from versions:、The conflict is caused by:、WARNING の行を読むと原因が分かる

株式会社RJCでは、pip をはじめとする Python の環境づくりの知識を、仲間と学び合っています。こうした知識を共有しながら、日々技術を磨いています。

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。