パッケージをインストールする#

この節では、 Python の パッケージ をインストールする方法の基本について示します。

この文脈では、 "パッケージ" という用語が、インストールされるソフトウェアの束を表すものである (すなわち、 配布物 の同義語である) ことを注記しておくことは重要です。 Python のなんらかのソースコードをインポートする (つまり、モジュール群の) 容れ物としての パッケージ のことを指してはいないのです。 Python のコミュニティでは、 配布物 のことを "パッケージ" という用語で呼ぶことは一般的に行われています。 Linux ディストロや、 Python そのもののようなその他の大きなソフトウェア配布物と紛らわしいので、 "配布物" という用語を使うことはしばしば歓迎されません。

パッケージをインストールするための必須事項#

この節では、その他の Python パッケージをインストールする前にやっておくべきステップを記します。

コマンドラインから Python を起動できることを確認する#

先へ進む前に、期待通りのバージョンの Python が手元のコマンドラインで動作していることを確認しておきましょう。つぎのコマンドを実行すれば確認できます:

python3 --version

py --version

Python 3.6.3 のような応答が出力されるはずです。もし Python がなければ、最新バージョンの 3.x を python.org からインストールするか、 Python ユーザのためのヒッチハイクガイドの Python をインストールする の節を参照するか、どちらかをしてください。

注釈

あなたがまだ慣れていなくて、しかも次のようなエラーに遭遇した場合には:

>>> python3 --version
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
NameError: name 'python3' is not defined

それは、このコマンドや、このチュートリアルに出てくる他のコマンドが、 シェル (ターミナル とか コンソール とも呼ばれます) で動作することを意図しているからです。オペレーティングシステムのシェルを使って Python とやりとりするための導入説明として、初心者のための Python はじめの第一歩チュートリアル <getting started tutorial を見てください。

注釈

IPython や Jupyter notebook のような拡張されたシェルを使っているのであれば、先頭に ! マークを付けることで、このチュートリアルに出てくるようなシステムコマンドを実行することができます:

In [1]: import sys
        !{sys.executable} --version
Python 3.6.3

現在動作している notebook の Python 実装 (これは python コマンドが実際に呼び出す Python 実装と同じであるとは限らない) で (投入した) コマンドが動作していることを確実にするために、 単に python と書くのではなく {sys.executable} と書くことを推奨します。

注釈

ほとんどの Linux ディストロが Python 3 の移植を扱う方法のせいで、仮想環境を作ること抜きでシステム側の Python を使う Linux ユーザは、まず、このチュートリアルに出てくる python コマンドを python3 に、そして、 python -m pip コマンドを python3 -m pip --user に置換するべきです。このチュートリアルに出てくるコマンドを sudo 付きで実行することは やめてください: パーミッションエラーが発生する場合には、仮想環境の作成の節に戻って仮想環境を作成し、チュートリアルに書かれている通りのやり方で再開してください。

コマンドラインから pip を実行できることを確実にする#

さらに、 pip コマンドを実行できることを確認しておきましょう。次のコマンドで確認できます:

python3 -m pip --version

py -m pip --version

python.org から持ってきたインストーラや Homebrew を使って Python をソースコードからインストールしたのであれば、すでに pip が動作するはずです。 Linux 上で OS のパッケージ管理機構を使ってインストールしたのであれば、 pip を個別にインストールしなければならないかもしれませんが、この場合は Linux パッケージマネージャを使って pip/setuptools/wheel をインストールする を見てください。

まだ pip がインストールされていなければ、初回は標準ライブラリからブートストラップしてみてください:

python3 -m ensurepip --default-pip

py -m ensurepip --default-pip

それでもまだ python -m pip を実行できないのであれば:

  • get-pip.py [1] をセキュアにダウンロードする

  • python get-pip.py を実行してください [2] 。これで pip をインストールまたは更新することができます。さらに、まだインストールされていなければ、 Setuptools と wheel もインストールされるでしょう。

    警告

    オペレーティングシステムないし他のパッケージ管理機構を使ってインストールした Python を管理しているなら、用心深くあるべきです。 get-pip.py はそのようなツール群と協調して動作する訳ではないので、あなたのシステムの一貫性を破壊するかもしれません。ソフトウェアをローカルにインストールするために設計された /usr/local にインストールするなら python get-pip.py --prefix=/usr/local を使うことができます。

pip ・ setuptools ・ wheel が最新版であることを確実にする#

pip 単体でも事前にビルドされたバイナリアーカイブからインストールを行うには十分ですが、最新の setuptools と wheel があればソースコードアーカイブからでも確実にインストールすることができるので便利です:

python3 -m pip install --upgrade pip setuptools wheel

py -m pip install --upgrade pip setuptools wheel

必須ではないが、仮想環境を構築する#

詳しいことは、 下の節 に出ていますので、ここでは基本的な venv [3] コマンドを典型的な Linux システムで使うやり方を説明します:

python3 -m venv tutorial_env
source tutorial_env/bin/activate

py -m venv tutorial_env
tutorial_env\Scripts\activate

これで新しい仮想環境が tutorial_env サブディレクトリ内に生成され、それを現在のシェルのデフォルトの python 環境として使わせることができます。

仮想環境を構築する#

Python の "仮想環境" を使えば、 Python の パッケージ をグローバルな環境にインストールする代わりに、特定のアプリケーションのための隔離された場所にインストールすることができます。グローバルなコマンドラインツールを安全にインストールしたいのであれば、 /guides/installing-stand-aline-command-line-tools を見てください。

手持ちのあるアプリケーションには LibFoo のバージョン 1 が必要で、しかし、別のアプリケーションではバージョン 2 を要求していると想像してみてください。このようなアプリケーションを両方同時に使うためにはどうすれば良いでしょうか？あらゆるものを /usr/lib/python3.6/site-packages (または、あなたが使っているプラットフォームの標準的な置き場所ならどこでも) にインストールするとすれば、容易く、アップグレードするべきでないはずのアプリケーションを意図せずアップグレードしてしまう結果に終わるでしょう。

あるいは、もっと一般的には、あるアプリケーションをインストールして、そのままにしておきたいとすればどうでしょう？アプリケーションが動作したとしても、ライブラリへの何らかの変更や、ライブラリのバージョン問題でアプリケーションが動作しなくなってしまうかもしれません。

あるいは、グローバルな site-packages ディレクトリに パッケージ をインストールすることができないとしたら、どうでしょうか？例えば、共有ホストのような。

このようなすべての場合において、仮想環境はあなたを助けることができます。仮想環境にはそれぞれのインストール先ディレクトリが別にあって、他の仮想環境とライブラリを共有するということがないからです。

現在、ふたつの Python 仮想環境を構築するためのツールがよく知られています:

  • venv は、 Python 3.3 およびそれ以降のバージョンで本体に同梱されていて利用可能であり、 Python 3.4 およびそれ以降では pip と Setuptools を作成された仮想環境内にインストールします (3.12 以前の Python のバージョンは Setuptools もインストールしていました) 。

  • virtualenv は別途インストールする必要がありますが、 Python 2.7+ と Python 3.3+ をサポートしており、 pip ・ Setuptools ・ wheel を作成された仮想環境に常にデフォルト (Python のバージョンに関係なく) でインストールします。

基本的な使い方は次の通りです:

venv を使うと:

python3 -m venv <DIR>
source <DIR>/bin/activate

py -m venv <DIR>
<DIR>\Scripts\activate

virtualenv を使うと:

python3 -m virtualenv <DIR>
source <DIR>/bin/activate

virtualenv <DIR>
<DIR>\Scripts\activate

さらなる説明は、 venv の説明文書や virtualenv の説明文書をみてください。

UNIX のシェル上で source を使うとそのシェル内では仮想環境用の変数が設定されますが、サブシェルでは設定され (ず、役に立つ効果が残り) ません。

上記のいずれの場合でも、 Windows ユーザは source コマンドを使うべき ではなく 、代わりに activate スクリプトをコマンドシェルから直接に実行するべきで、例えば次のようにします:

<DIR>\Scripts\activate

複数の仮想環境をそのままで管理することはうんざりする作業になりがちなので、 依存関係を管理するためのチュートリアル では、より抽象度の高いツール Pipenv を使ってプロジェクトやアプリケーションのそれぞれのために作成した個別の仮想環境群を自動的に管理する方法を紹介しています。

pip を使ってインストールする#

pip は推奨されているインストーラです。以下に最もよくある使用シナリオを挙げます。より詳しくは、 リファレンスガイド の全体を含む pip 説明文書 を見てください。

PyPI からインストールする#

pip の最もよくある使い方は、 要求事項指定子 を用いて Python パッケージインデックス からインストールすることです。一般的には、要求事項識別子は、プロジェクト名と後続する省略可能な バージョン指定子 で構成されています。 バージョン指定子仕様 に、サポートされている識別子の完全な説明があります。以下にいくつかの例を挙げます。

"とあるプロジェクト" の最新版をインストールするには:

python3 -m pip install "SomeProject"

py -m pip install "SomeProject"

特定のバージョンをインストールするには:

python3 -m pip install "SomeProject==1.4"

py -m pip install "SomeProject==1.4"

あるバージョンと同じか新しいバージョンで、もう一つのものより古いものをインストールするには:

python3 -m pip install "SomeProject>=1,<2"

py -m pip install "SomeProject>=1,<2"

To install a version that's compatible with a certain version: [4]

python3 -m pip install "SomeProject~=1.4.2"

py -m pip install "SomeProject~=1.4.2"

この場合には、 "==1.4.*" で、かつ、 ">=1.4.2" であるバージョンをインストールするという意味になります。

ソースコード配布物 vs. Wheels#

pip は、 ソースコード配布物 (sdist) または Wheels のどちらからでもインストールすることができますが、両方が PyPI に存在している場合には pip は互換性のある wheel を選好します。例えば --no-binary オプションを使うことで pip のデフォルト動作を上書き修正することができます。

Wheels は、ビルド済みの 配布物 フォーマットで、特にプロジェクトがコンパイル済み拡張を含んでいる場合には、 ソースコード配布物 (sdist) に比べてより短時間でインストールすることができます。

pip がインストールするべき wheel を発見できなかった場合には、手元で wheel をビルドして、将来のインストール時に再びソースコード配布物からリビルドしないで済むようにキャッシュしておきます。

パッケージを更新する#

インストール済みの とあるプロジェクト を PyPI から最新版に更新する。

python3 -m pip install --upgrade SomeProject

py -m pip install --upgrade SomeProject

ユーザサイトへインストールする#

パッケージ を現在のユーザだけが使えるように他から隔離してインストールするには --user フラグを使います:

python3 -m pip install --user SomeProject

py -m pip install --user SomeProject

もっと詳しい情報を知りたければ、pip 説明文書の ユーザ限定のインストール の節を見てください。

仮想環境の中では --user フラグが無効になることに注意してください - すべてのインストールコマンドが仮想環境に影響を与えます。

とあるプロジェクト がコマンドラインスクリプトかコンソールエントリポイントをひとつでも定義しているのであれば、 --user を与えることで 、 ユーザベース のバイナリ置き場、それがシェルの PATH 変数にあろうがなかろうが、そこにインストールすることになるでしょう (バージョン 10 以降の pip では、スクリプトを PATH に含まれていないパスにインストールする時には警告を表示します)。インストール後にスクリプトが利用可能でない場合には、 PATH にそのディレクトリパスを追加する必要があるでしょう:

  • Linux や macOS 上では、 python -m site --user-base を実行した結果の末尾に bin を追加すれば、ユーザベースのバイナリ置き場となるディレクトリがどこであるかがわかるでしょう。例えば、このコマンドは大抵の場合に ~/.local (の ~ をあなたのホームディレクトリの絶対パスに展開したもの) を表示しますが、すると、 PATH には ~/.local/bin を追加する必要があるということです。 ~/.profile を修正する ことで PATH を恒久的に変更することができます。

  • Windows 上では、 py -m site --user-site の結果について site-packages を Scripts で置き換えればユーザベースのバイナリ置き場となるディレクトリを見つけることができるでしょう。このコマンドは例えば C:\Users\Username\AppData\Roaming\Python36\site-packages のような結果を返すので、 PATH に C:\Users\Username\AppData\Roaming\Python36\Scripts が含まれるようにする必要があるでしょう。 Control Panel で恒久的に PATH を設定することができるでしょう。 PATH の修正が効果を持つには、一旦ログアウトする必要があるかもしれません。

Requirementsファイル#

Requirements ファイル で指定された一連の必須条件となる依存先をインストールしましょう。

python3 -m pip install -r requirements.txt

py -m pip install -r requirements.txt

VCS からインストールする#

プロジェクトを VCS から "編集可能" モードでインストールしましょう。この構文を全て細かく説明したものについては、 VCS サポート の pip の節を見てください。

python3 -m pip install -e SomeProject @ git+https://git.repo/some_pkg.git          # from git
python3 -m pip install -e SomeProject @ hg+https://hg.repo/some_pkg                # from mercurial
python3 -m pip install -e SomeProject @ svn+svn://svn.repo/some_pkg/trunk/         # from svn
python3 -m pip install -e SomeProject @ git+https://git.repo/some_pkg.git@feature  # from a branch

py -m pip install -e SomeProject @ git+https://git.repo/some_pkg.git          # from git
py -m pip install -e SomeProject @ hg+https://hg.repo/some_pkg                # from mercurial
py -m pip install -e SomeProject @ svn+svn://svn.repo/some_pkg/trunk/         # from svn
py -m pip install -e SomeProject @ git+https://git.repo/some_pkg.git@feature  # from a branch

他のインデックスサイトからインストールする#

代替となるインデックスサイトからインストールする

python3 -m pip install --index-url http://my.package.repo/simple/ SomeProject

py -m pip install --index-url http://my.package.repo/simple/ SomeProject

PyPI に加えて、追加のインデックスサイトをインストール中に探索する

python3 -m pip install --extra-index-url http://my.package.repo/simple SomeProject

py -m pip install --extra-index-url http://my.package.repo/simple SomeProject

ローカルのソースツリーからインストールする#

開発モード 、すなわち、プロジェクトがインストールされていて、しかも、ソースツリーからへんしゅうかのうであるような方法でローカルのソースツリーからインストールすること。

python3 -m pip install -e <path>

py -m pip install -e <path>

ソースツリーから通常通りにインストールすることも可能

python3 -m pip install <path>

py -m pip install <path>

ローカルアーカイブからインストールする#

特定のソースコードアーカイブファイルをインストールする。

python3 -m pip install ./downloads/SomeProject-1.0.4.tar.gz

py -m pip install ./downloads/SomeProject-1.0.4.tar.gz

アーカイブを含んだローカルのディレクトリから(しかも PyPI をチェックしないで)インストールする

python3 -m pip install --no-index --find-links=file:///local/dir/ SomeProject
python3 -m pip install --no-index --find-links=/local/dir/ SomeProject
python3 -m pip install --no-index --find-links=relative/dir/ SomeProject

py -m pip install --no-index --find-links=file:///local/dir/ SomeProject
py -m pip install --no-index --find-links=/local/dir/ SomeProject
py -m pip install --no-index --find-links=relative/dir/ SomeProject

他の場所からインストールする#

simple repository API 準拠のフォーマットに合わせてデータを表現するようなヘルパーアプリケーションを作成して、 pip を --extra-index-url フラグでそのインデックスへ向け直すことで、他のデータソース (例えば Amazon S3 ストレージ) からインストールすることができます。

./s3helper --port=7777
python -m pip install --extra-index-url http://localhost:7777 SomeProject

リリース前のバージョンをインストールする#

安定バージョンに加えて、リリース前のバージョンや開発中のバージョンを見つけましょう。デフォルトでは pip は安定バージョンだけを探索します。

python3 -m pip install --pre SomeProject

py -m pip install --pre SomeProject

パッケージの "Extras" をインストールする#

Extras は、パッケージのオプション的な "変種" で、追加的な依存先を加えることも可能であり、従って、パッケージの追加的な機能を有効化することができるものです。もし、one なる機能を追加するとわかっているパッケージの追加部分 (extra) をインストールしたいのであれば、次のような pip のインストールコマンドを使うことでそれを追加することができます:

python3 -m pip install 'SomePackage[PDF]'
python3 -m pip install 'SomePackage[PDF]==3.0'
python3 -m pip install -e '.[PDF]'  # editable project in current directory

py -m pip install "SomePackage[PDF]"
py -m pip install "SomePackage[PDF]==3.0"
py -m pip install -e ".[PDF]"  # editable project in current directory