ユーザーガイド¶

パッケージのインストール¶

pipは PyPI からのインストール、バージョン管理からのインストール、ローカルプロジェクトからインストール、配布ファイルからのインストールをサポートしています。

最も一般的なシナリオは、PyPI から 要件指定子 を使用してインストールすることです。

$ pip install SomePackage            # latest version
$ pip install SomePackage==1.0.4     # specific version
$ pip install 'SomePackage>=1.0.4'     # minimum version

詳細および例については、pip install のリファレンスを参照してください。

Requirementsファイル¶

"Requirementsファイル"は、pip install でインストールするためのパッケージリストが記載されているファイルです。

pip install -r requirements.txt

ファイル形式に関する詳細は、ここにあります: Requirementsファイル形式

論理的に言うと、Requirementsファイルはファイルに書かれた pip install 引数のリストに過ぎません。特定の順序でpipによってインストールされているファイル内のパッケージに頼るべきではないことに注意してください。

実際には、Requirementsファイルには4つの一般的な用途があります。

1. Requirementsファイルは、repeatable installations を実現するため、pip freeze からの結果を保持するために使用されます。この場合、pip freeze が実行されたとき、requirementファイルにはインストールされたすべての固定バージョンのリストが記載されています。

   pip freeze > requirements.txt
   pip install -r requirements.txt
   

2. Requirementsファイルは、依存関係を適切に解決させるためにpipを使用します。pipは 正しい依存性解決方法を持っていません 。代わりにシンプルにプロジェクトで見つけた最初の仕様を使用します。例えば、pkg1 は pkg3>=1.0 が必要で、pkg2 に pkg3>=1.0,<=2.0 が必要で、pkg1 が最初に解決された場合、pipは pkg3>=1.0 のみを使用し、　pkg2 で必要だけどコンフリクトする pkg3 のバージョンをインストールします。この問題を解決するには、pkg3>=1.0,<=2.0 （つまり、正しい仕様）をrequirementsファイルに他の最上位要件とともに直接配置できます。:

   pkg1
   pkg2
   pkg3>=1.0,<=2.0
   

3. Requirementsファイルは、pipにサブ依存関係の代替バージョンをインストールさせるために使用されます。たとえば、最新バージョン（v1.3）にバグがあるが ProjectB を必須とするRequirementsファイル内の`ProjectA` を仮定した場合、pipに以前のバージョンのを受け入れるよう強制することができます。:

   ProjectA
   ProjectB<1.3
   

4. Requirementsファイルは、バージョン管理に存在するローカルパッチとの依存関係を上書きするために使用されます。たとえば、依存関係、PyPIの SomeDependency にバグがあり、上流の修正を待つことができないとします。ソースコードをクローン/コピーして修正を加え、いくつかのタグを付けてバージョン管理システムに配置することができます。以下のようなコマンドでrequirementsファイルで参照したいと思います。:

   git+https://myvcs.com/some_dependency@sometag#egg=SomeDependency
   

   前もって SomeDependency がrequirementファイルにトップレベルの要件であった場合は、その行を新しい行に 置き換え ます。SomeDependency が従属依存である場合、新しい行を 追加 します。

pipは、プロジェクトに埋め込まれた requirements.txt ファイルを検出するのではなく、 install_requires metadata を使用してパッケージの依存関係を判断することが重要です。

こちらも参照下さい:

• Requirementsファイル形式
• pip freeze
• "setup.py vs requirements.txt" (an article by Donald Stufft)

Constraintsファイル¶

Constraintsファイルは、インストールされているかどうかではなく、インストールされている要件のバージョンのみを制御するrequirementsファイルです。その構文と内容は Requirementsファイル とほぼ同じです。重要な違いが1つあります:constraintsファイルにパッケージを組み込んでも、パッケージのインストールが開始されません。

以下のように制約ファイルを使用して下さい:

pip install -c constraints.txt

Constraintsファイルは、インストールするものが正確にわからないときに、requirementsファイルとまったく同じ理由で使用されます。例えば、あなたの環境では"helloworld"パッケージが動作しないので、あなたはローカルパッチバージョンを持っているとします。あなたがインストールするものは"helloworld"に依存しているものもあれば、そうでないものもあります。

パッチバージョンが一貫して使用されることを保証する1つの方法は、インストールするすべての依存関係を手動で監査することです。そして"helloworld"が存在する場合は、そのものをインストールするときに使用するrequirementsファイルを書きます。

Constraintsファイルはより良い方法を提供します:組織のための単一のconstraintsファイルを作成し、あらゆる場所で使用します。インストールするものに"helloworld"をインストールする必要がある場合、あなたのconstraintsファイルで指定された固定バージョンが使用されます。

Constraintsファイルのサポートはpip7.1で追加されました。

Wheelsからインストール¶

"Wheel"は、ソースアーカイブからのビルドやインストールと比較して、インストールを大幅に高速化できるビルドされたアーカイブ形式です。詳細は、Wheel docs 、PEP427、および PEP425 を参照してください。

pipはWheelsが利用可能な環境を好みます。これを無効にするには、pip install に --no-binary フラグを使用して下さい。

満足できるwheelsが見つからない場合、pipはデフォルトでソースアーカイブを検索します。

wheelアーカイブから直接インストールするには:

pip install SomePackage-1.0-py2.py3-none-any.whl

wheelsが利用できない場合、pipは利便性を高めるため pip wheel を勧め、すべての要件と依存関係に対応するwheelsを構築します。

pip wheel は wheel package がインストールされている必要があります。これはwheel packageが使用する "bdist_wheel" setuptoolsの拡張機能を提供します。

要件とそのすべての依存関係のwheelsをローカルディレクトリに構築するには:

pip install wheel
pip wheel --wheel-dir=/local/wheels -r requirements.txt

then、wheelsのローカルディレクトリ（PyPIからではなく）を使用してこれらの要件をインストールします。

pip install --no-index --find-links=/local/wheels -r requirements.txt

パッケージのアンインストール¶

pipは以下のようにほとんどのパッケージをアンインストールできます:

$ pip uninstall SomePackage

pipは、新しいバージョンにアップグレードする前に、古いバージョンのパッケージを自動的にアンインストールします。

詳細と例については、pip uninstall のリファレンスを参照してください。

パッケージの一覧表示¶

インストールされたパッケージを一覧表示するには:

$ pip list
docutils (0.9.1)
Jinja2 (2.6)
Pygments (1.5)
Sphinx (1.1.2)

古いパッケージを一覧表示し、最新のバージョンを表示するには:

$ pip list --outdated
docutils (Current: 0.9.1 Latest: 0.10)
Sphinx (Current: 1.1.2 Latest: 1.1.3)

インストールされたパッケージの詳細を表示するには:

$ pip show sphinx
---
Name: Sphinx
Version: 1.1.3
Location: /my/env/lib/pythonx.x/site-packages
Requires: Pygments, Jinja2, docutils

詳細および例については、pip list および pip show のリファレンスページを参照してください。

パッケージの検索¶

pipは、pip search コマンドを使用してパッケージの PyPI を検索できます:

$ pip search "query"

queryは、すべてのパッケージの名前とサマリーを検索するために使用されます。

詳細および例については、pip search のリファレンスを参照してください。

コンフィグレーション¶

[global]
timeout = 60
index-url = http://download.zope.org/ppix

[global]
timeout = 60

[freeze]
timeout = 10

[install]
ignore-installed = true
no-dependencies = yes

[global]
no-cache-dir = false

[install]
no-compile = no

[global]
find-links =
    http://download.example.com

[install]
find-links =
    http://mirror1.example.com
    http://mirror2.example.com

export PIP_DEFAULT_TIMEOUT=60

pip --default-timeout=60 [...]

export PIP_FIND_LINKS="http://mirror1.example.com http://mirror2.example.com"

pip install --find-links=http://mirror1.example.com --find-links=http://mirror2.example.com

$ pip completion --bash >> ~/.profile

$ pip completion --zsh >> ~/.zprofile

$ pip completion --fish > ~/.config/fish/completions/pip.fish

eval "`pip completion --bash`"

ローカルパッケージからのインストール¶

場合によっては、PyPIへアクセスせず、ローカルパッケージからのみインストールすることもできます。

まず、要件を満たすアーカイブをダウンロードします:

$ pip install --download DIR -r requirements.txt

PyPIからダウンロードしようとする前に、まず pip install --download がwheelキャッシュを見に行くことに注意してください。前もって要件をインストールしていない場合は、それらのwheelキャッシュはありません。その場合、PyPIからwheelsを取得していない要件がいくつかあり、wheelsが必要な場合は代わりに次のように実行します:

$ pip wheel --wheel-dir DIR -r requirements.txt

次に、ローカルからのみインストールするには、--find-links と --no-index を使用します:

$ pip install --no-index --find-links=DIR -r requirements.txt

"必要な場合のみ"再帰的アップグレード¶

pip install --upgrade は現在、熱心な再帰的なアップグレードを実行するために書かれています。つまり、新しい親の要件を満たしているかどうかにかかわらず、すべての依存関係をアップグレードします。

例えば、仮定すると

• SomePackage-1.0 は AnotherPackage>=1.0 が必要
• SomePackage-2.0 は AnotherPackage>=1.0 と OneMorePackage==1.0 が必要
• SomePackage-1.0 と AnotherPackage-1.0 は現在インストールされている
• SomePackage-2.0 と AnotherPackage-2.0 PyPIで利用できる最新バージョン

pip install --upgrade SomePackage を実行することは、AnotherPackage がすでに満たされているにもかかわらず、SomePackage と AnotherPackage をアップグレードします。

pipには現在のところ、"必要な場合のみ"再帰的なアップグレードを行うオプションはありませんが、次の2つの手順で実現できます:

pip install --upgrade --no-deps SomePackage
pip install SomePackage

最初の行は SomePackage をアップグレードしますが、AnotherPackage のような依存関係はアップグレードしません。2行目は OneMorePackage のような新しい依存関係を埋めます。

"必要な場合のみ"再帰的に新しい pip upgrade コマンドのデフォルトの動作を行う計画については:issue:59 を参照してください。

ユーザーインストール¶

Python 2.6では、インストールのための "user scheme" for installation が提供されました。つまり、すべてのPythonディストリビューションは、ユーザーに固有の代替インストール場所をサポートしています。各OSのデフォルトの場所は、site.USER_BASE variable. のpythonのドキュメントで説明しています。このインストールモードは、pip install に --user オプションを指定することで有効にすることができます。

さらに、 "user scheme"は、site.USER_BASE の値を更新する``PYTHONUSERBASE`` 環境変数を設定することでカスタマイズできます。

'/ myappenv'にカスタマイズされたsite.USER_BASEを持つ環境に"SomePackage"をインストールするには、次のようにします:

export PYTHONUSERBASE=/myappenv
pip install --user SomePackage

pip install --user は次の4つのルールに従います:

1. グローバルにインストールされたパッケージがpythonパス上にあり、インストール要件と コンフリクト する場合、パッケージは無視され、アンインストール されません。
2. グローバルにインストールされたパッケージがpythonパス上にあり、インストール要件を 満たしている 時、pipは何もせず、要件が満たされているとレポートします。(--system-site-packages virtualenvにパッケージをインストールする際にグローバルパッケージがどのように要件を満たすかと同様)
3. pipは、ユーザサイトがpythonパス上にないため、--no-site-packages virtualenv（つまり、デフォルトのvirtualenv）に --user installを実行しません。
4. --system-site-packages virtualenvでは、pipはvirtualenv site-packages内のパッケージとコンフリクトするパッケージをインストールしません。--userのインストールにはsys.pathの優先順位がなく、無意味です。

ルールをより明確にするために、ここにいくつかの例があります:

--no-site-packages virtualenv（デフォルトの種類）内から:

$ pip install --user SomePackage
Can not perform a '--user' install. User site-packages are not visible in this virtualenv.

SomePackage==0.3 が既にvirtualenvにインストールされている``--system-site-packages`` virtualenv内から:

$ pip install --user SomePackage==0.4
Will not install to the user site because it will lack sys.path precedence

SomePackage がグローバルにインストール されていない 実際のPythonの中から:

$ pip install --user SomePackage
[...]
Successfully installed SomePackage

SomePackage がグローバルにインストール されている が、最新バージョン ではない 実際のPython内から

$ pip install --user SomePackage
[...]
Requirement already satisfied (use --upgrade to upgrade)

$ pip install --user --upgrade SomePackage
[...]
Successfully installed SomePackage

SomePackage がグローバルにインストールされていて、最新のバージョンの実際のPythonの中から:

$ pip install --user SomePackage
[...]
Requirement already satisfied (use --upgrade to upgrade)

$ pip install --user --upgrade SomePackage
[...]
Requirement already up-to-date: SomePackage

# force the install
$ pip install --user --ignore-installed SomePackage
[...]
Successfully installed SomePackage

繰り返し性の確保¶

pipは様々なレベルの再現性を達成することができます

SomePackage == 1.2.3
DependencyOfSomePackage == 4.5.6

FooProject == 1.2 --hash=sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824

$ tempdir=$(mktemp -d /tmp/wheelhouse-XXXXX)
$ pip wheel -r requirements.txt --wheel-dir=$tempdir
$ cwd=`pwd`
$ (cd "$tempdir"; tar -cjvf "$cwd/bundled.tar.bz2" *)

$ tempdir=$(mktemp -d /tmp/wheelhouse-XXXXX)
$ (cd $tempdir; tar -xvf /path/to/bundled.tar.bz2)
$ pip install --force-reinstall --ignore-installed --upgrade --no-index --no-deps $tempdir/*