【Pythonエンジニア必携】pip逆引きリファレンス（2024年版）

# はじめに
みずほリサーチ&テクノロジーズの@fujineです。本記事では、**pipの各コマンドやオプションをユースケース毎に整理してみました**。

`pip`はPython開発環境構築の必需品である一方、サブコマンドやオプションが多数あり、使いこなすのは中々難しいものです。私も忘れる度に何度も調べ直していたことから、今回改めて整理するに至りました。

Pythonの初学者のみならず、「こんな時ってどのオプション使うんだっけ？」と悩んだ時の参考にしていただければ幸いです。

|コマンド|解説内容|
|:--|:--|
|[pip install](#pip-install)|パッケージのインストール|
|[pip uninstall](#pip-uninstall)|パッケージのアンインストール|
|[pip download](#pip-download)|パッケージのダウンロード|
|[pip hash](#pip-hash)|パッケージのハッシュ値確認|
|[pip list](#pip-list)|インストール済みパッケージの一覧出力|
|[pip freeze](#pip-freeze)|同上|
|[pip show](#pip-show)|インストール済みパッケージの詳細情報出力|
|[pip check](#pip-check)|インストール済みパッケージの依存状態を検証|
|[pip cache](#pip-cache)|pipキャッシュ機能の管理|
|[pip config](#pip-config)|pipの各種設定|
|[pip debug](#pip-debug)|環境情報の確認|

:::note warn
- pipでは、複数のコマンドで共通的に使用できる[汎用オプション](https://pip.pypa.io/en/stable/cli/pip/#general-options)と、個々のコマンドでのみ有効なオプション（サブコマンド）があります。本記事では説明の便宜上、両者を特段区別せずに解説して行きます。
- [search](https://pip.pypa.io/en/stable/cli/pip_search/)コマンドは2022年から[非推奨](https://warehouse.pypa.io/api-reference/xml-rpc.html#deprecated-methods)となっています。パッケージを検索する際は、ブラウザにて[PyPIサイト](https://pypi.org)から検索して下さい。
- [inspect](https://pip.pypa.io/en/stable/cli/pip_inspect/)と[wheel](https://pip.pypa.io/en/stable/cli/pip_wheel/)コマンドは、本記事では割愛いたします。
:::

# 用語
本記事で使用する用語と意味を整理します。

|用語|意味|
|:--|:--|
|[配布パッケージ](https://packaging.python.org/ja/latest/glossary/#term-Distribution-Package)|リソースファイルを含むバージョン付きのアーカイブファイルです。単に「パッケージ」とも呼びます。|
|[パッケージインデックス](https://packaging.python.org/ja/latest/glossary/#term-Package-Index)|パッケージが保管・公開されているリポジトリです。|
|[PyPI](https://packaging.python.org/ja/latest/glossary/#term-Python-Package-Index-PyPI)|Pythonコミュニティの公式パッケージインデックスです。「パイピーアイ」と呼びます。|
|[pip](https://packaging.python.org/ja/latest/key_projects/#pip)|Python公式のパッケージインストーラです（Python3.4以降は標準で付属）。PyPIやその他のパッケージインデックスから、パッケージを検索・ダウンロード・インストールすることが出来ます。|
|[requirementsファイル](https://pip.pypa.io/en/latest/user_guide/#requirements-files)|パッケージ要件を定義するためのテキストファイルです。一般的には`requirements.txt`というファイル名にします。|
|[バイナリ配布物](https://packaging.python.org/ja/latest/specifications/binary-distribution-format/)|ビルド済みの配布パッケージです。ファイルは`.whl`拡張子で、エンドユーザーは「置く」だけでパッケージを利用出来ます。|
|[ソースコード配布物](https://packaging.python.org/ja/latest/specifications/source-distribution-format/)|ソースコードとビルドスクリプトが配布されたパッケージです。ファイルは`tar.gz`拡張子で、エンドユーザーはソースコードをビルドする必要があります。|
|[pyproject.toml](https://packaging.python.org/ja/latest/specifications/pyproject-toml/)|Pythonアプリケーションのプロジェクト定義ファイルです。ビルドバックエンドや依存パッケージ等を指定でき、[従来の`setup.py`に代わるものとして推奨](https://packaging.python.org/ja/latest/guides/modernize-setup-py-project/)されています。|

# 検証環境
`venv`で検証用の仮想環境を作成します。
```sh
$ python -m venv lab
$ cd lab
$ source bin/activate
```

実行環境のOSと、Pythonとpipのバージョンは以下の通りです。
```sh
$ cat /etc/debian_version 
11.8

$ python -V && pip -V
Python 3.12.2
pip 24.0
```

:::note warn
以降の解説では、パッケージが何もインストールされていない真っ白な仮想環境での挙動を解説します。
同じパッケージの別バージョン、もしくは依存関係にある他パッケージがすでにインストール済みの場合、コマンドの実行結果（インストールされるバージョン等）が変わる可能性がありますのでご了承下さい。
:::

# pip install
パッケージのインストールには、[pip install](https://pip.pypa.io/en/stable/cli/pip_install/)コマンドを使用します。

## 基本のインストール
引数に指定したパッケージを`PyPI`インデックスからインストールします。バージョンを指定しない場合、インストール可能な最新の安定バージョンが自動的に選択されます。
```sh
$ pip install fastapi
```
パッケージは複数指定可能です。複数指定すると、パッケージ同士の依存関係を満たすバージョンがインストールされます。依存関係によっては、最新バージョンが選択されない場合もあります。
```sh
$ pip install fastapi uvicorn[standard]
```

:::note warn
[beautifulsoup4](https://pypi.org/project/beautifulsoup4/)のように、インストールとインポートで指定するパッケージ名が異なる場合もあります。詳細は各パッケージの公式ドキュメントをご確認下さい。

```sh:インストール時
$ pip install beautifulsoup4
```

```python:インポート時
from bs4 import BeautifulSoup
```
:::

## `requirements`ファイルからインストール
[`-r`（もしくは--requirement）](https://pip.pypa.io/en/stable/cli/pip_install/#cmdoption-r)オプションで、`requirements`ファイルに定義されたパッケージ群を一括インストールします。
```requirements.txt
fastapi
uvicorn[standard]
```

```sh
$ pip install -r requirements.txt 
```

`-r`を連結して、複数の`requirements`ファイルから同時インストールすることも可能です。
```requirements-tests.txt 
pytest
```

```sh
$ pip install -r requirements.txt -r requirements-tests.txt 
```

## バージョンを指定してインストール
[依存関係指定子](https://packaging.python.org/ja/latest/specifications/dependency-specifiers/)を使用して、バージョンの有効範囲を指定します。
```sh
$ pip install fastapi==0.110.0
```

代表的な指定子とその指定範囲の例を以下に整理します。詳細な仕様は[Version specifiers](https://packaging.python.org/en/latest/specifications/version-specifiers/#version-specifiers)をご参照下さい。

|指定子の例|意味|バージョンの指定範囲|
|:--|:--|:--|
|`==3.1`|[Version matching](https://peps.python.org/pep-0440/#version-matching)|`3.1`および`3.1.*`|
|`~=3.1`|[Compatible release](https://peps.python.org/pep-0440/#compatible-release)|`3.1`以上かつ`3.*`|
|`>=3.1`|[Inclusive ordered comparison](https://peps.python.org/pep-0440/#inclusive-ordered-comparison)|`3.1`以上|
|`<3.1`|[Exclusive ordered comparison](https://peps.python.org/pep-0440/#exclusive-ordered-comparison)|`3.1`未満|
|`!=3.1`|[Version exclusion](https://peps.python.org/pep-0440/#version-exclusion)|`3.1`を除く|

## 依存パッケージを除いてインストール
[--no-deps](https://pip.pypa.io/en/stable/cli/pip_install/#cmdoption-no-deps)オプションを指定すると、依存パッケージはスキップされ、引数のパッケージのみがインストールされます。
```sh
$ pip install --no-deps fastapi
```

## VCS（バージョン管理システム）からインストール
`git+<リポジトリURL>`でGitリポジトリから直接インストールします。Gitの他、Subversion、Mercurial、Bazaarなど[複数のVCSをサポート](https://pip.pypa.io/en/stable/topics/vcs-support/)しています。
```sh
$ pip install git+https://github.com/tiangolo/fastapi.git
```

## `pyproject.toml`からインストール
[パッケージングガイド](https://packaging.python.org/ja/latest/guides/writing-pyproject-toml/)を参考に、最低限の情報を記載した`pyproject.toml`を用意します。
```pyproject.toml
[build-system]
requires = ["setuptools >= 69.0"]
build-backend = "setuptools.build_meta"

[project]
requires-python = ">= 3.12"
version = "1.0"
name = "api-demo"
dependencies = ["fastapi >= 0.110.0", "uvicorn[standard] >= 0.27.1"]

[project.optional-dependencies]
tests = ["pytest >= 8.0.0"]
```

`pyproject.toml`があるディレクトリ（カレントディレクトリなら`.`）を指定すると、`[project.dependencies]`テーブルに定義された必須パッケージがインストールされます。
```sh
$ pip install .
```

`[project.optional-dependencies]`テーブルに定義された追加パッケージは、`ディレクトリパス[オプション名]`と指定することで必須パッケージと併せてインストールされます。
```sh
$ pip install .[tests]
```

## 編集モードでインストール
[`-e`（もしくは`--editable`）](https://pip.pypa.io/en/stable/cli/pip_install/#cmdoption-e)オプションを使用すると、パッケージの変更内容が即時更新されるようになります。自作パッケージの開発などで便利なオプションです。
```sh
$ pip install -e .
```

## プロキシ環境でインストール
[--proxy](https://pip.pypa.io/en/stable/cli/pip/#cmdoption-proxy)オプションでプロキシサーバーの接続情報を指定します。`--proxy`オプションの他、[設定ファイルや環境変数を用いたプロキシ設定](https://pip.pypa.io/en/stable/user_guide/#using-a-proxy-server)も可能です。

```sh
$ pip install --proxy scheme://[user:pw@]proxy.server:port fastapi
```

:::note info
プロキシ環境下で継続的に開発作業する場合、毎回オプション指定するのは手間ですので、設定ファイルや環境変数を活用した方が良いでしょう。
:::

## オフライン環境でインストール
他の環境からパッケージファイルを入手しておくことで、インターネットに接続できないオフライン環境に対してもパッケージのインストールが可能です。

事前準備として、後述する[pip download章](#pip-download)を参考に、別環境でダウンロードしたパッケージをオフライン環境にローカル保存します。**依存パッケージも全て保存する**必要があります。
```sh
$ ls pkgs
annotated_types-0.6.0-py3-none-any.whl
anyio-4.3.0-py3-none-any.whl
fastapi-0.110.0-py3-none-any.whl
idna-3.6-py3-none-any.whl
pydantic-2.6.3-py3-none-any.whl
pydantic_core-2.16.3-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
sniffio-1.3.1-py3-none-any.whl
starlette-0.36.3-py3-none-any.whl
typing_extensions-4.10.0-py3-none-any.whl
```

次に、[`--no-index`](https://pip.pypa.io/en/stable/cli/pip_install/#cmdoption-no-index)オプションで`PyPI`へのアクセスをスキップし、[`-f`（もしくは`--find-links`）](https://pip.pypa.io/en/stable/cli/pip_install/#cmdoption-f)オプションでパッケージのローカルディレクトリを指定します。

```sh
$ pip install --no-index -f pkgs fastapi
```

## プライベートリポジトリからインストール
社内やクラウドサービス上でホストされているプライベートリポジトリからインストールすることも可能です。

[`-i`（もしくは`--index-url`）](https://pip.pypa.io/en/stable/cli/pip_install/#cmdoption-i)オプションでプライベートリポジトリURLを指定します。この場合、プライベートリポジトリ**のみ**から検索され、`PyPI`にはアクセスされません。

```sh
$ pip install -i http://my.package.repo/simple SomePackage
```

[`--extra-index-url`](https://pip.pypa.io/en/stable/cli/pip_install/#cmdoption-extra-index-url)オプションを指定すると、`PyPI`とプライベートリポジトリの**両方から**検索されます。

```sh
$ pip install --extra-index-url http://my.package.repo/simple SomePackage 
```

:::note warn
`--extra-index-url`オプションでは、[`PyPI`と追加リポジトリの優先順位を指定することは**出来ません**](https://stackoverflow.com/questions/67253141/python-pip-priority-order-with-index-url-and-extra-index-url)。自作パッケージであれば独自のプレフィックスを付けるなど、インデックス同士でパッケージ名が重複しないようにする必要があります。
:::

:::note alert
プライベートリポジトリを使用する場合、[依存関係かく乱攻撃(Dependency Confusion)](https://japan.zdnet.com/article/35166404/)に注意してください。同攻撃への対策として[PEP708（リポジトリAPIの拡張）](https://peps.python.org/pep-0708/)が提案されています。
:::

## インストール済みのパッケージをアップグレード
[`-U`（もしくは`--upgrade`）](https://pip.pypa.io/en/stable/cli/pip_install/#cmdoption-U)オプションにより、古いパッケージが最新バージョンにアップグレードされます。
```sh
$ pip install -U fastapi
```

[`--upgrade-strategy`](https://pip.pypa.io/en/stable/cli/pip_install/#cmdoption-upgrade-strategy)オプションにて、依存パッケージのアップグレード戦略を指定します。
- `only-if-needed`（デフォルト） : 依存関係を満たせる場合のみアップグレードされます。
- `eager` : 依存関係を無視して全てアップグレードされます。

```sh
$ pip install -U --upgrade-strategy only-if-needed fastapi
$ pip install -U --upgrade-strategy eager fastapi
```

:::note alert
`eager`にて依存パッケージを強制的にアップグレードすると、依存関係が満たされなくなることがありますのでご注意下さい。
:::

## ドライラン
[--dry-run](https://pip.pypa.io/en/stable/cli/pip_install/#cmdoption-dry-run)オプションを指定すると、パッケージの依存解決とダウンロードのみが実行され、インストールはされません。「どんなパッケージとバージョンがインストールされるか」を事前に確認することができます。

```sh
$ pip install --dry-run fastapi
```

## キャッシュを使用せずにインストール
pipには[キャッシュ機能](https://pip.pypa.io/en/stable/topics/caching/)があり、一度ダウンロードしたパッケージファイルはキャッシュに保存され、同一バージョンが再インストールされる際にはキャッシュから再利用されます。

[--no-cache-dir](https://pip.pypa.io/en/stable/cli/pip/#cmdoption-no-cache-dir)オプションを指定するとキャッシュが無効化され、パッケージを毎回ダウンロードしてインストールします。

```sh
$ pip install --no-cache-dir fastapi
```

:::note info
通常は無効化する必要はありませんが、[Dockerイメージをビルド](https://pip.pypa.io/en/stable/topics/caching/#disabling-caching)する際にキャッシュを無効化すると、イメージサイズを小さくすることに役立ちます。
:::

## メッセージの出力レベルを変更
[`-v`（もしくは`--verbose`）](https://pip.pypa.io/en/stable/cli/pip/#verbose)で出力メッセージが詳細化され、反対に[`-q`（もしくは`--quiet`）](https://pip.pypa.io/en/stable/cli/pip/#cmdoption-q)で出力メッセージが抑止されます。
```sh
$ pip install -v fastapi
$ pip install -q fastapi
```

## 低速なネットワーク環境でインストール
ネットワーク帯域が低速な環境では、ダウンロードが頻繁にタイムアウトしがちです。

[`--retries`](https://pip.pypa.io/en/stable/cli/pip/#cmdoption-retries)オプションでリトライ回数（デフォルトは5回）、[`--timeout`](https://pip.pypa.io/en/stable/cli/pip/#cmdoption-timeout)でソケットのタイムアウト時間（デフォルトは15秒）をそれぞれ変更可能です。

```sh
$ pip install --retries 10 --timeout 60 fastapi
```

# pip uninstall
パッケージのアンインストールには、[pip uninstall](https://pip.pypa.io/en/stable/cli/pip_uninstall/)コマンドを使用します。

## パッケージをアンインストール
指定したパッケージをアンインストールします。

```sh
$ pip uninstall fastapi
```

:::note warn
**依存パッケージは自動的にアンインストールされません**。これらも安全にアンインストールしたい場合は、[pip-autoremove](https://github.com/invl/pip-autoremove)等を試してみて下さい。
:::

## 確認入力（`Proceed (Y/n)? `）をスキップ
[`-y`（もしくは`--yes`）](https://pip.pypa.io/en/stable/cli/pip_uninstall/)オプションで、アンインストール時の確認入力をスキップできます。
```sh
$ pip uninstall -y fastapi
```

:::note info
大量のパッケージを一気に削除する時に便利なオプションです。
:::

## `requirements.txt`からアンインストール
インストールと同様、[`-r`（もしくは`--requirement`）](https://pip.pypa.io/en/stable/cli/pip_uninstall/#cmdoption-r)オプションで`requirements.txt`からのアンインストールも可能です。`requirements.txt`に記載されていない依存パッケージは削除されません。
```sh
$ pip uninstall -r requirements.txt
```

# pip download
パッケージのダウンロードには、[pip download](https://pip.pypa.io/en/stable/cli/pip_download/)コマンドを使用します。

## パッケージをダウンロード
パッケージとその依存パッケージをダウンロードします。[`-d`（もしくは`--dest`）](https://pip.pypa.io/en/stable/cli/pip_download/#cmdoption-d)オプションで保存先のディレクトリを指定します。デフォルトはカレントディレクトリです。

```sh
$ pip download -d pkgs fastapi

$ ls pkgs
annotated_types-0.6.0-py3-none-any.whl
anyio-4.2.0-py3-none-any.whl
fastapi-0.109.2-py3-none-any.whl
idna-3.6-py3-none-any.whl
pydantic-2.6.1-py3-none-any.whl
pydantic_core-2.16.2-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
sniffio-1.3.0-py3-none-any.whl
starlette-0.36.3-py3-none-any.whl
typing_extensions-4.9.0-py3-none-any.whl
```

ビルド済みパッケージは[プラットフォームの互換性タグ](https://packaging.python.org/ja/latest/specifications/platform-compatibility-tags/#overview)に基づき、`{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-{platform tag}.whl`というファイル名となっています。

## ダウンロード環境とインストール環境が異なる場合のダウンロード方法
パッケージがOSやPythonバージョン毎にビルドされている場合、同一バージョンのパッケージが複数種公開されていることがあります。例えば`fastapi`の依存パッケージである[pydantic-core](https://github.com/pydantic/pydantic-core)は、[v2.16.2](https://pypi.org/project/pydantic-core/2.16.2/#files)だけで78種類ものバイナリパッケージが公開されています！

:::note warn
pipの`install`や`download`では、（後述するオプションを指定しない場合）**pipコマンドを実行した環境に適合するバイナリパッケージが自動的に選択**されます。そのため、例えばLinux環境で（オプション無しで）ダウンロードしたパッケージをWindows環境でインストールしても失敗してしまいます。
:::

特定の環境でインストール可能なパッケージをダウンロードするには、**PythonのバージョンやOS情報などを指定**する必要があります。例えば、Windows(64bit) + CPython3.11で実行可能な`pydantic-core`をダウンロードするには以下のように実行します。

```sh
$ pip download --python-version 311 --platform win_amd64 --implementation cp --only-binary :all: pydantic-core

$ ls pydantic_core*.whl
pydantic_core-2.16.3-cp311-none-win_amd64.whl
```

各オプションでは、
- [`--python-version`](https://pip.pypa.io/en/stable/cli/pip_download/#cmdoption-python-version) : Pythonバージョン
- [`--platform`](https://pip.pypa.io/en/stable/cli/pip_download/#cmdoption-platform) : [プラットフォームタグ](https://packaging.python.org/ja/latest/specifications/platform-compatibility-tags/#platform-tag)
- [`--implementation`](https://pip.pypa.io/en/stable/cli/pip_download/#cmdoption-implementation) : [Pythonタグ](https://packaging.python.org/ja/latest/specifications/platform-compatibility-tags/#python-tag)
- [`--only-binary`](https://pip.pypa.io/en/stable/cli/pip_download/#cmdoption-only-binary) : バイナリパッケージのみを対象とする

をそれぞれ指定しています。`--platform`や`--implementation`に指定すべき値が分からない場合は、後述する[pip debugコマンド](#pip-debug)で確認してみて下さい。

:::note info
[Examples](https://pip.pypa.io/en/stable/cli/pip_download/#examples)にも多数事例が紹介されていますので、こちらもご参照下さい。
:::

# pip hash
パッケージのハッシュ値を確認するには、[pip hash](https://pip.pypa.io/en/stable/cli/pip_hash/)コマンドを使用します。

## パッケージのハッシュ値を確認
`pip hash`でパッケージのSHA256ハッシュ値を出力します。
```sh
$ pip download --no-deps fastapi

$ pip hash fastapi-0.110.0-py3-none-any.whl 
fastapi-0.110.0-py3-none-any.whl:
--hash=sha256:87a1f6fb632a218222c5984be540055346a8f5d8a68e8f6fb647b1dc9934de4b
```

[`-a`（もしくは`--algorithm`）](https://pip.pypa.io/en/stable/cli/pip_hash/#cmdoption-a)でハッシュアルゴリズムを指定できます。指定できるのは`sha256`、`sha384`、`sha512`の3種類です。
```sh
$ pip hash -a sha384 fastapi-0.110.0-py3-none-any.whl 
fastapi-0.110.0-py3-none-any.whl:
--hash=sha384:01fc38819a25d75fdc71b68bc27fc670b656d0bf68a75ec9d11d1cf1c929ef9eabca00e802ffb6977d7e59cddcc19fc3

$ pip hash -a sha512 fastapi-0.110.0-py3-none-any.whl 
fastapi-0.110.0-py3-none-any.whl:
--hash=sha512:89847575d1c597317d98a738eb4a192d67c90f049d7e58ae41fe9222e42fac8be7a33324dd6f1490f7b664304827f67a60a10225e981fd78b69fb2c62d309bd8
```

:::note info
インストール前にハッシュ値を確認することで、パッケージファイルが破損・改ざんされていないことを検証できます。
:::

# pip list
インストール済みのパッケージ情報を一覧で出力するには、[pip list](https://pip.pypa.io/en/stable/cli/pip_list/)コマンドを使用します。

以降の章では、`fastapi`をインストール済みという前提で解説していきます。

## インストール済みのパッケージを一覧出力
`pip list`でインストール済みのパッケージ名とバージョンが一覧出力されます。

```sh
$ pip list
Package           Version
----------------- -------
annotated-types   0.6.0
anyio             4.3.0
fastapi           0.110.0
idna              3.6
pip               24.0
pydantic          2.6.3
pydantic_core     2.16.3
sniffio           1.3.1
starlette         0.36.3
typing_extensions 4.10.0
```

:::note warn
`pip freeze`と異なり、`pip list`ではpipやsetuptoolなどのパッケージングツールも出力されます。
:::

## 特定のパッケージを除外して一覧出力
[`--exclude`](https://pip.pypa.io/en/stable/cli/pip_list/#cmdoption-exclude)オプションを指定することで、特定のパッケージが一覧から除外されます。

```sh
$ pip list --exclude pip 
Package           Version
----------------- -------
annotated-types   0.6.0
anyio             4.3.0
fastapi           0.110.0
idna              3.6
pydantic          2.6.3
pydantic_core     2.16.3
sniffio           1.3.1
starlette         0.36.3
typing_extensions 4.10.0
```

## 最新ではないパッケージのみを出力
[`-o`（もしくは`--outdated`）](https://pip.pypa.io/en/stable/cli/pip_list/#cmdoption-o)オプションで、最新バージョンではないパッケージのみが出力されます。
```sh
$ pip list -o
Package   Version Latest Type
--------- ------- ------ -----
starlette 0.36.3  0.37.2 wheel
```

:::note info
パッケージが最新かどうかを一括で確認するのに役立ちます。
:::

## 最新パッケージのみを出力
[`-u`（もしくは`uptodate`）](https://pip.pypa.io/en/stable/cli/pip_list/#cmdoption-u)オプションで、最新バージョンのパッケージのみを出力できます。
```sh
$ pip list -u
Package           Version
----------------- -------
annotated-types   0.6.0
anyio             4.3.0
fastapi           0.110.0
idna              3.6
pip               24.0
pydantic          2.6.3
pydantic_core     2.16.3
sniffio           1.3.1
typing_extensions 4.10.0
```

## 依存パッケージを除いて出力
[`--not-required`](https://pip.pypa.io/en/stable/cli/pip_list/#cmdoption-not-required)オプションで、依存パッケージ**ではない**パッケージのみが出力されます。

```sh
$ pip list --not-required
Package Version
------- -------
fastapi 0.110.0
pip     24.0
```

:::note info
`-o`と`--not-required`を組み合わせれば、**「他パッケージに依存されていない & アップグレード可能なパッケージ」を簡単に調べることができます。**
:::


## 出力フォーマットを変更
[`--format`](https://pip.pypa.io/en/stable/cli/pip_list/#cmdoption-format)オプションで出力フォーマットを変更します。指定できるのは`columns`（デフォルト）、`freeze`、`json`の3種類です。

`freeze`を指定すると、`pip freeze`と同じ[requirements形式](https://pip.pypa.io/en/stable/reference/requirements-file-format/)で出力されます。
```sh
$ pip list --format freeze
annotated-types==0.6.0
anyio==4.2.0
fastapi==0.109.2
idna==3.6
pip==24.0
pydantic==2.6.1
pydantic_core==2.16.2
sniffio==1.3.0
starlette==0.36.3
typing_extensions==4.9.0
```

`json`を指定するとJSONL(JSON Lines)フォーマットになります。JSONへの変換には、`jq`の他、Python標準の[jsonコマンドラインツール](https://docs.python.org/ja/3/library/json.html#module-json.tool)でも整形可能です。
```sh
$ pip list --format json
[{"name": "annotated-types", "version": "0.6.0"}, {"name": "anyio", "version": "4.3.0"}, {"name": "fastapi", "version": "0.110.0"}, {"name": "idna", "version": "3.6"}, {"name": "pip", "version": "24.0"}, {"name": "pydantic", "version": "2.6.3"}, {"name": "pydantic_core", "version": "2.16.3"}, {"name": "sniffio", "version": "1.3.1"}, {"name": "starlette", "version": "0.36.3"}, {"name": "typing_extensions", "version": "4.10.0"}]

$ pip list --format json | python -m json.tool
[
    {
        "name": "annotated-types",
        "version": "0.6.0"
    },
    {
        "name": "anyio",
        "version": "4.3.0"
    },
    {
        "name": "fastapi",
        "version": "0.110.0"
    },
    {
        "name": "idna",
        "version": "3.6"
    },
    {
        "name": "pip",
        "version": "24.0"
    },
    {
        "name": "pydantic",
        "version": "2.6.3"
    },
    {
        "name": "pydantic_core",
        "version": "2.16.3"
    },
    {
        "name": "sniffio",
        "version": "1.3.1"
    },
    {
        "name": "starlette",
        "version": "0.36.3"
    },
    {
        "name": "typing_extensions",
        "version": "4.10.0"
    }
]
```

# pip freeze
[pip freeze](https://pip.pypa.io/en/stable/cli/pip_freeze/)コマンドでも、インストール済みパッケージを一覧化できます。

## パッケージ一覧を`requirements`形式で出力
パッケージ情報を`requirements`形式で出力します。

```sh
$ pip freeze
annotated-types==0.6.0
anyio==4.2.0
fastapi==0.109.2
idna==3.6
pydantic==2.6.1
pydantic_core==2.16.2
sniffio==1.3.0
starlette==0.36.3
typing_extensions==4.9.0
```

`freeze`コマンドは通常、`requirements.txt`ファイルを作成するのに使用します。
```sh
$ pip freeze > requirements.txt
```

:::note info
`pip list`と違い、`pip freeze`では`pip`や`setuptools`などのパッケージングツールは出力**されません。** これらも出力したい場合は、[`--all`](https://pip.pypa.io/en/stable/cli/pip_freeze/#cmdoption-all)オプションを使用して下さい。
:::

# pip show
インストール済みパッケージの詳細情報を確認するには、[pip show](https://pip.pypa.io/en/stable/cli/pip_show/)コマンドを使用します。

## パッケージの詳細情報を出力
引数に指定したパッケージの詳細情報を出力します。パッケージは複数指定可能です。

以下のように、パッケージの概要（`Summary`）、ライセンス（`License`）、依存するパッケージ（`Requires`）、依存されているパッケージ（`Required-by`）などが確認出来ます。
```sh
$ pip show fastapi pydantic
Name: fastapi
Version: 0.110.0
Summary: FastAPI framework, high performance, easy to learn, fast to code, ready for production
Home-page: 
Author: 
Author-email: Sebastián Ramírez <tiangolo@gmail.com>
License: 
Location: /tmp/lab/lib/python3.12/site-packages
Requires: pydantic, starlette, typing-extensions
Required-by: 
---
Name: pydantic
Version: 2.6.3
Summary: Data validation using Python type hints
Home-page: 
Author: 
Author-email: Samuel Colvin <s@muelcolvin.com>, Eric Jolibois <em.jolibois@gmail.com>, Hasan Ramezani <hasan.r67@gmail.com>, Adrian Garcia Badaracco <1755071+adriangb@users.noreply.github.com>, Terrence Dorsey <terry@pydantic.dev>, David Montague <david@pydantic.dev>, Serge Matveenko <lig@countzero.co>, Marcelo Trylesinski <marcelotryle@gmail.com>, Sydney Runkle <sydneymarierunkle@gmail.com>, David Hewitt <mail@davidhewitt.io>
License: 
Location: /tmp/lab/lib/python3.12/site-packages
Requires: annotated-types, pydantic-core, typing-extensions
Required-by: fastapi
```

:::note info
`-v`オプションを追加すると、[Classifiers](https://packaging.python.org/ja/latest/guides/writing-pyproject-toml/#classifiers)や[Entry-points](https://packaging.python.org/ja/latest/guides/writing-pyproject-toml/#advanced-plugins)などの詳細情報も確認出来ます。
:::

# pip check
インストール済みパッケージ同士の依存関係をチェックするには、[pip check](https://pip.pypa.io/en/stable/cli/pip_check/)コマンドを使用します。

## インストール済みパッケージの依存関係を検証
`pip check`でインストール済みパッケージの依存関係を検証します。`No broken requirements found.`と出力されれば、依存関係は正しい状態です。
```sh
$ pip install fastapi
$ pip check 
No broken requirements found.
```

`fastapi`の依存パッケージの1つである`pydantic`をアンインストールして再チェックすると、依存関係を満たさないためエラーとなります。
```sh
$ pip uninstall -y pydantic
$ pip check
fastapi 0.110.0 requires pydantic, which is not installed.
```

# pip cache
pipの[キャッシュ機能](https://pip.pypa.io/en/stable/topics/caching/)を管理するには、[pip cache](https://pip.pypa.io/en/stable/cli/pip_cache/)コマンドを使用します。

## キャッシュの場所を確認
`pip cache dir`でキャッシュの保存場所が確認できます。

```sh
$ pip cache dir
/home/username/.cache/pip
```
## キャッシュの使用状況を確認
`pip cache info`でキャッシュのディスク使用量を確認できます。以下の例では、合計で132件、32.8MBがキャッシュされていることが分かります。
```sh
$ pip cache info
Package index page cache location (pip v23.3+): /home/username/.cache/pip/http-v2
Package index page cache location (older pips): /home/username/.cache/pip/http
Package index page cache size: 32.8 MB
Number of HTTP files: 132
Locally built wheels location: /home/username/.cache/pip/wheels
Locally built wheels size: 0 bytes
Number of locally built wheels: 0
```
## キャッシュをクリア
`pip cache purge`でキャッシュをクリアします。
```sh
$ pip cache purge
Files removed: 132
```

:::note info
複数の機械学習パッケージを使用したり、多種大量のパッケージをインストールするようなケースでは、**キャッシュが数百MB〜数GBまで肥大化する**ことがあります。そのままではディスク使用量を圧迫するため、**定期的にキャッシュを削除する**ことをお勧めします。
:::

# pip config
pipの設定ファイルを操作するには、[pip config](https://pip.pypa.io/en/stable/cli/pip_config/)コマンドを使用します。

:::note info
pipの設定ファイルには以下[3つのレベル（≒スコープ）](https://pip.pypa.io/en/stable/topics/configuration/#configuration-files)が存在します。

- `global` : システム単位
- `user` : ユーザー単位
- `site` : `virtualenv`などの仮想環境単位

設定ファイルが複数定義されている場合、[`global` -> `user` -> `site`の順に評価・上書き](https://pip.pypa.io/en/stable/topics/configuration/#loading-order)されます。例えば、`global`と`user`で同じ設定項目が異なる値で設定されていた場合、`user`の設定値で上書きされます。
:::

## 設定ファイルを作成
まずは設定ファイルを手動で作成します。`user`レベルの設定をする場合、`Unix`環境では`$HOME/.config/pip/pip.conf`に作成します。

```sh
$ touch $HOME/.config/pip/pip.conf
```

:::note warn
設定ファイルのパスやファイル名は、[OSや設定レベル毎に異なります](https://pip.pypa.io/en/stable/topics/configuration/#location)。`user`レベルの設定ファイルパスは以下の通りです。

|OS|設定ファイルパス（`user`）|
|:-:|:--|
|Unix|`$HOME/.config/pip/pip.conf`もしくは`$HOME/.pip/pip.conf`|
|Windows|``%APPDATA%\pip\pip.ini``|
|MaxOS|`$HOME/Library/Application Support/pip/pip.conf` <br> もしくは`$HOME/.config/pip/pip.conf` <br> もしくは`$HOME/.pip/pip.conf`|

:::

設定ファイルは[`INI`フォーマットで記述](https://pip.pypa.io/en/stable/topics/configuration/#configuration-files)します。設定例を以下に示します。

```ini:$HOME/.config/pip/pip.conf
[global]
; pipコマンド全体のタイムアウト値
timeout = 60

[uninstall]
; pip uninstall時に、-y(--yes)をデフォルトで設定
yes = true

[list]
; pip list時に、--format`を`freeze`形式に設定
format = freeze
```

:::note warn
`[global]`というセクション名が使われていますが、これは前述した設定ファイルの`global`レベル**ではなく**、pipコマンド全体に使用可能な[汎用オプション](https://pip.pypa.io/en/stable/cli/pip/#general-options)のことを指します。
:::

以降の解説用に、`site`（仮想環境）レベルの設定ファイルも一緒に作成してみます。`site`の場合は、仮想環境ディレクトリの直下に`pip.conf`（Windowsの場合は`pip.ini`）を作成します。タイムアウト値は`user`よりも短い45秒に設定しました。

```ini:pip.conf
[global]
; pipコマンド全体のタイムアウト値
timeout = 45
```

## 設定値を確認
`pip config list`で、設定ファイルの値が一覧出力されます。`user`と`site`で2つの設定ファイルを作成したため、重複する`global.timeout`の設定値は`site`の値になっていることが確認できます。

```sh
$ pip config list
global.timeout='45'
list.format='freeze'
uninstall.yes='true'
```

[--global / --user / --site](https://pip.pypa.io/en/stable/cli/pip_config/#options)オプションのいずれかを指定することで、上書きされる前の設定値を確認できます。

```sh
$ pip config list --global

$ pip config list --user
global.timeout='60'
list.format='freeze'
uninstall.yes='true'

$ pip config list --site
global.timeout='45'
```

特定の設定項目のみを確認したい場合は、`pip config get`を使用します。こちらも、前述した`--global` / `--user` / `--site`オプションを指定可能です。

```sh
$ pip config get global.timeout
45

$ pip config get global.timeout --global
ERROR: No such key - global.timeout

$ pip config get global.timeout --user
60

$ pip config get global.timeout --site
45
```

## 設定ファイルの場所を確認する
`pip config debug`で、設定ファイルのパスと設定値が出力されます。

```sh
$ pip config debug
env_var:
env:
global:
  /etc/xdg/pip/pip.conf, exists: False
  /etc/pip.conf, exists: False
site:
  /tmp/lab/pip.conf, exists: True
    global.timeout: 45
user:
  /home/username/.pip/pip.conf, exists: False
  /home/username/.config/pip/pip.conf, exists: True
    global.timeout: 60
    uninstall.yes: true
    list.format: freeze
```

:::note info
環境変数や設定ファイルが期待通りに反映されない場合のデバッグに役立ちます。
:::

# pip debug
pipを使用する環境情報を取得するには、[pip debug](https://pip.pypa.io/en/stable/cli/pip_debug/)コマンドを使用します。

## 環境情報を取得
`pip debug`で環境情報が出力されます。pipやPythonのパスやプラットフォーム情報などを確認できます。

```sh
$ pip debug
WARNING: This command is only meant for debugging. Do not use this with automation for parsing and getting these details, since the output and options of this command may change without notice.
pip version: pip 24.0 from /tmp/lab/lib/python3.12/site-packages/pip (python 3.12)
sys.version: 3.12.2 (main, Feb  7 2024, 02:58:54) [GCC 10.2.1 20210110]
sys.executable: /home/username/lab/bin/python3.12
sys.getdefaultencoding: utf-8
sys.getfilesystemencoding: utf-8
locale.getpreferredencoding: UTF-8
sys.platform: linux
sys.implementation:
  name: cpython
'cert' config value: global
REQUESTS_CA_BUNDLE: None
CURL_CA_BUNDLE: None
pip._vendor.certifi.where(): /tmp/lab/lib/python3.12/site-packages/pip/_vendor/certifi/cacert.pem
pip._vendor.DEBUNDLED: False
(中略)
Compatible tags: 852
  cp312-cp312-manylinux_2_31_x86_64
  cp312-cp312-manylinux_2_30_x86_64
  cp312-cp312-manylinux_2_29_x86_64
  cp312-cp312-manylinux_2_28_x86_64
  cp312-cp312-manylinux_2_27_x86_64
  cp312-cp312-manylinux_2_26_x86_64
  cp312-cp312-manylinux_2_25_x86_64
  cp312-cp312-manylinux_2_24_x86_64
  cp312-cp312-manylinux_2_23_x86_64
  cp312-cp312-manylinux_2_22_x86_64
  ...
  [First 10 tags shown. Pass --verbose to show all.]
```

:::note info
`Compatible tags`を見ることで、その環境にインストール可能な[プラットフォームの互換性タグ](https://packaging.python.org/ja/latest/specifications/platform-compatibility-tags/#overview)を確認することが可能です。これは、前述した[pip download章](#pip-download)にて`--platform`、`--implementation`、`--abi`等の値を特定するのに役立ちます。
:::

:::note warn
以下メッセージで警告されている通り、この情報はデバッグのみを目的としており、出力内容は予告なしに変更される可能性がありますのでご注意下さい。
> WARNING: This command is only meant for debugging. Do not use this with automation for parsing and getting these details, since the output and options of this command may change without notice.
:::

# 終わりに
本記事では、`pip`の各コマンドやオプションをユースケース毎にご紹介しました。

今回は仮想環境を用いたシンプルな事例でしたので、環境構築で多いトラブルや疑問点については、別記事にて改めて整理したいと思います。