ユーザーガイド

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

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は 正しい依存性解決方法を持っていません 。代わりにシンプルにプロジェクトで見つけた最初の仕様を使用します。例えば、pkg1pkg3>=1.0 が必要で、pkg2pkg3>=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 を使用してパッケージの依存関係を判断することが重要です。

こちらも参照下さい:

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 docsPEP427、および 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 wheelwheel 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 のリファレンスを参照してください。

コンフィグレーション

設定ファイル

pipでは標準のiniスタイルの設定ファイルにすべてのコマンドラインオプションのデフォルトを設定することができます。

設定ファイルの名前と場所は、プラットフォームによって多少異なります。ユーザー単位、vertualenv単位、またはサイト全体(すべてのユーザーで共有)の設定が可能です。

ユーザー単位

  • Unixでは、デフォルトの設定ファイルは、XDG_CONFIG_HOME 環境変数を重んじる $HOME/.config/pip/pip.conf です。

  • macOSでは、設定ファイルは $HOME/Library/Application Support/pip/pip.conf です。

  • Windowsでは、設定ファイルは %APPDATA%\pip\pip.ini です。

また、従来のユーザーごとの設定ファイルもありますがこれも尊重されています。これらは以下の場所に位置します。

  • UnixやmacOSでは、設定ファイルは $HOME/.pip/pip.conf です。

  • Windowsでは、設定ファイルは %HOME%\pip\pip.ini です。

環境変数 PIP_CONFIG_FILE を使用して、この設定ファイルのカスタムパスの場所を設定できます。

virtualenv内

  • UnixとmacOSのファイルは $VIRTUAL_ENV/pip.conf です。

  • Windowsではファイルは %VIRTUAL_ENV%\pip.ini です。

サイト全体

  • Unixでは、ファイルは /etc/pip.conf にあります。代わりに、/etc/xdg/pip/pip.conf のように、環境変数 XDG_CONFIG_DIRS (存在する場合)に設定されているパスのいずれかの "pip"サブディレクトリに存在する可能性があります。

  • macOSではファイルは /Library/Application Support/pip/pip.conf です。

  • Windows XPの場合、ファイルは C:\Documents and Settings\All Users\Application Data\pip\pip.ini です。

  • Windows7以降では、ファイルは非表示になっていますが、C:\ProgramData\pip\pip.ini に書き込むことができます

  • サイト全体の設定はWindows Vistaではサポートされていません

複数の設定ファイルがpipによって見つかった場合、それらは次の順序で結合されます

  1. まずサイト全体のファイルを読み込み、次に

  2. ユーザーごとのファイルが読み込まれ、最後に

  3. virtualenv固有のファイルが読み込まれます。

以前のファイルから読み取られた値は、読み込まれた各ファイルを上書きするので、サイト全体のファイルとユーザー単位のファイルの両方でグローバルタイムアウトが指定されている場合は、後者の値が使用されます。

設定の名前は長いコマンドラインのオプションから導かれます。例えば、別のパッケージインデックス(--index-url)を使用し、HTTPタイムアウト(--default-timeout)を60秒に設定すると、設定ファイルは次のようになります

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

各サブコマンドは、同じ名前ですべてのグローバル設定が上書きされるように、オプションで独自のセクションで設定できます。例えば、freeze (Freezing Requirements) コマンドを実行しているときの timeout10 秒に減らし、他のすべてのコマンドは 60 秒にすることも可能です:

[global]
timeout = 60

[freeze]
timeout = 10

--ignore-installed--no-dependencies などのBooleanオプションは次のように設定できます:

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

booleanオプション --no-compile--no-cache-dir を有効にするには、falsy値を使用する必要があります:

[global]
no-cache-dir = false

[install]
no-compile = no

--find-links のようなオプションを複数行に書くことができます:

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

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

環境変数

pipのコマンドラインオプションは、PIP_<UPPER_LONG_NAME> の形式で環境変数を設定することができます。ダッシュ(-)はアンダースコア(_)で置き換える必要があります。

例えば、デフォルトのタイムアウトを設定するには、次のようにします:

export PIP_DEFAULT_TIMEOUT=60

これはpipに直接オプションを渡すのと同じです:

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

設定の優先順位

コマンドラインオプションは環境変数よりも優先されます。環境変数は設定ファイルよりも優先されます。

設定ファイル内では、コマンド固有セクションがグローバルセクションよりも優先されます。

例:

  • --host=fooPIP_HOST=foo を上書きします。

  • PIP_HOST=foo[global] host = foo で設定ファイルを上書きします。

  • 設定ファイル [<command>] host = bar のコマンド固有のセクションは、[global] 設定ファイルセクションに同じ名前のオプションを上書きします。

コマンドの完了

pipは、bash、zsh、およびfishのコマンドライン補完をサポートしています。

bashを設定するには:

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

zshを設定するには:

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

fishの設定

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

あるいは、completion コマンドの結果をシェルのeval関数で直接使用することもできます。例えば、スタートアップファイルに以下を追加します:

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.0AnotherPackage>=1.0 が必要

  • SomePackage-2.0AnotherPackage>=1.0OneMorePackage==1.0 が必要

  • SomePackage-1.0AnotherPackage-1.0 は現在インストールされている

  • SomePackage-2.0AnotherPackage-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は様々なレベルの再現性を達成することができます

固定されたバージョン番号

requirementsファイル内の依存関係のバージョンを固定することで、新しくリリースされたバージョンのバグや非互換性から守ることができます:

SomePackage == 1.2.3
DependencyOfSomePackage == 4.5.6

pip freeze をrequirementsファイルを生成すると、トップレベルの依存関係だけでなくそのサブ依存関係も確実に含まれます。明示的に記載されていないものをインストールしないようにするには、--no-deps を使用してインストールを実行します。

この戦略は実装が容易で、OSやアーキテクチャ全体で機能します。ただし、PyPIと認証局チェーンを信頼します。また、バージョンを増やすことなくパッケージを変更できないインデックスや検索リンクの場所にも依存しています。(PyPIはこれを防ぎます。)

ハッシュチェックモード

バージョン番号を固定する以外に、ダウンロードされたパッケージを検証するためのハッシュを追加することができます:

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

これにより、PyPIまたはHTTPS証明書チェーンの侵害から保護されます。また、バージョン番号を変更することなくパッケージを変更することもできます(これを可能にするインデックス上で)。このアプローチは、自動化されたサーバーの配置に適しています。

ハッシュチェックモードは、承認されたパッケージを含むプライベートインデックスサーバーを実行するための省力化の代替方法です:パッケージのアップロード、ACLの管理、監査証跡(VCSが要件ファイルに無料で提供する)を保持する必要がなくなります。また、ベンダーライブラリを代用することもできます。これにより、アップグレードが容易になり、VCSノイズが少なくなりますもちろん、プライベートインデックスやベンダーライブラリの可用性のメリットはありません。

詳細については、pip install's discussion of hash-checking mode を参照してください。

インストールバンドル

pip wheel を使用すると、コンパイルが完了したすべてのプロジェクトの依存関係を1つのアーカイブにまとめることができます。これにより、インデックスサーバーが使用できなくなり、時間のかかる再コンパイルが行われない場合のインストールが可能になります。次のようなアーカイブを作成します:

$ 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/*

コンパイルされたパッケージは、通常、OS固有およびアーキテクチャ固有であるため、これらのアーカイブは必ずしもマシン間で移植可能であるとは限りません。

この方法と一緒に、ハッシュチェックモードを使用して、将来のアーカイブが同一のパッケージで構築されるようにすることができます。

警告

最後に、setup.pysetup_requires キーワード引数に注意してください。それを使用する(まれな)パッケージは、その依存関係をsetuptoolsによって直接ダウンロードし、pipの保護をスキップします。このようなパッケージを使用する必要がある場合は、Controlling setup_requires を参照してください。