pip と venv を使って仮想環境にパッケージをインストールする#

このガイド文書では、標準ライブラリの仮想環境ツール venv を使って仮想環境を作成し活性化する方法と、パッケージをインストールする方法について議論します。このガイド文書は次のようなことを行う方法をカバーします:

  • 仮想環境を作成し活性化する

  • pip の準備をする

  • pip コマンドを使って仮想環境にパッケージをインストールする

  • requirements ファイルを使う、作成する

注釈

このガイド文書は、サポートされている Python のバージョン、現時点では 3.8 およびこれ以降のものに適用されます。

注釈

この文書では、 パッケージ という用語を通常は外部のホストからインストールされる 配布パッケージ の意味で使います。これは Python ソースコードでモジュールをインポートするという意味で使われる インポートパッケージ とは異なります。

重要

このガイド文書は、 <https://www.python.org/downloads/> から取得する公式の Python を使っていることを前提条件にしています。Python をインストールするのにオペレーティングシステムのパッケージマネージャを使っているのであれば、ここに述べるようなステップを進める前に、Python がインストールされていることを確実にしてください。

仮想環境を構築し使用する#

新しい仮想環境を作成する#

venv (Python 3 用) を使うと、異なるプロジェクトにそれぞれ別のパッケージをインストールして管理できます。(仮想環境は) 互いに影響を与えない"仮想的な" Python インストール環境を生成します。別のプロジェクトに移動すると、他の仮想環境から隔離された新しい仮想環境を作成することができます。仮想環境を使うことで、パッケージ群を自信を持ってインストールすることができ、他のプロジェクトの環境には干渉しないであろうことから、あなたは利益を得ることができます。

Tip

第三者のパッケージ群を使う時には仮想環境を用いることが推奨されます。

仮想環境を作成するには、プロジェクトのディレクトリへ行って次のようなコマンドを実行してください。これによって、ローカルの .venv フォルダに新しい仮想環境ができるでしょう:

python3 -m venv .venv

py -m venv .venv

二つ目の引数は、仮想環境を作成するべき場所の指定です。一般的には、プロジェクトのルートディレクトリに .venv という名前で作成します。

venv は仮想的な Python を .venv ディレクトリの中にインストールするでしょう。

注釈

仮想環境のディレクトリは、 .gitignore やその類似物を使ってバージョン管理システムから除外しておくべきです。

仮想環境を活性化する#

仮想環境に (依存先の) パッケージをインストールして使用できるようにするには、まず 仮想環境 を activate しなければなりません。仮想環境を活性化すると、その仮想環境に特有の python と pip の実行ファイルがシェルの PATH 変数に追加されます。

source .venv/bin/activate

.venv\Scripts\activate

仮想環境が activate されたことを確認するには、 Python インタープリタの場所を確かめましょう:

which python

where python

仮想環境が active である間は、上記のコマンドは .venv ディレクトリを含むファイルパスを出力することでしょう、つまり以下のようになって終了します:

.venv/bin/python

.venv\Scripts\python

仮想環境が active である間は、pip はパッケージをその仮想環境内にインストールします。これによって、あなたの Python アプリケーションからそのパッケージをインポートして使用することができるようになります。

仮想環境を非活性化 <deactivate> する#

プロジェクトを切り替えたい、あるいは、仮想環境から離脱したい時は、仮想環境を deactivate してください:

deactivate

注釈

シェルを終了すれば、仮想環境を非活性化 <deactivate> することになるでしょう。もし、新しいシェル窓を開いて、そこで仮想環境を使いたい時は、再活性化 <reactivate> してください。

仮想環境を再活性化 <reactivate> する#

既存の仮想環境を活性化 <activate> したい場合は、仮想環境の活性化に関する上述のやり方に従ってください。新しい仮想環境を作成する必要はありません。

pip の準備をする#

pip は Python の参照モデルとなるパッケージマネージャです。仮想環境内でパッケージのインストールや更新に用いられます。

MacOS 用の Python インストーラは pip を含んでいます。Linux では、 python3-pip のような追加のパッケージをインストールしなければならないかもしれません。以下のようにすると pip が最新版であることを確実にすることができます:

python3 -m pip install --upgrade pip
python3 -m pip --version

それから、ユーザサイトには最新版の pip がインストールされているはずです:

pip 23.3.1 from .../.venv/lib/python3.9/site-packages (python 3.9)

Windows 用の Python インストーラは pip を含んでいます。以下のようにすると pip が最新版であることを確実にすることができます:

py -m pip install --upgrade pip
py -m pip --version

その後、pip が最新版になっているはずです:

pip 23.3.1 from .venv\lib\site-packages (Python 3.9.4)

pip を使ってパッケージをインストールする#

仮想環境が活性化状態にある時には、パッケージ群をインストールすることができます。パッケージをインストールするには pip install コマンドを使ってください。

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

例として、 Python Package Index (PyPI) から Requests ライブラリをインストールしてみましょう:

python3 -m pip install requests

py -m pip install requests

pip が requests とその依存先パッケージをすべてダウンロードしてインストールするはずです:

Collecting requests
  Using cached requests-2.18.4-py2.py3-none-any.whl
Collecting chardet<3.1.0,>=3.0.2 (from requests)
  Using cached chardet-3.0.4-py2.py3-none-any.whl
Collecting urllib3<1.23,>=1.21.1 (from requests)
  Using cached urllib3-1.22-py2.py3-none-any.whl
Collecting certifi>=2017.4.17 (from requests)
  Using cached certifi-2017.7.27.1-py2.py3-none-any.whl
Collecting idna<2.7,>=2.5 (from requests)
  Using cached idna-2.6-py2.py3-none-any.whl
Installing collected packages: chardet, urllib3, certifi, idna, requests
Successfully installed certifi-2017.7.27.1 chardet-3.0.4 idna-2.6 requests-2.18.4 urllib3-1.22

特定のバージョンのパッケージをインストールする#

バージョン指定子 を使えば、 pip でパッケージのバージョンを指定してインストールすることができます。例えば、 requests の特定のバージョンをインストールするなら:

python3 -m pip install 'requests==2.18.4'

py -m pip install "requests==2.18.4"

requests の最新の 2.x リリースをインストールするには:

python3 -m pip install 'requests>=2.0.0,<3.0.0'

py -m pip install "requests>=2.0.0,<3.0.0"

--pre フラグを使ってパッケージのリリース前のバージョンをインストールするには:

python3 -m pip install --pre requests

py -m pip install --pre requests

(パッケージの) extra 部分をインストールする#

必須ではない extra 部分を持つものがパッケージの中にはあります。extra の名前を角括弧([, ])の中に書くことで pip にインストールするように指示することができます。

python3 -m pip install 'requests[security]'

py -m pip install "requests[security]"

ソースコードからパッケージをインストールする#

pip は、ソースコードから直接にパッケージをインストールすることができます。例えば、 google-auth ディレクトリの中にあるソースコードをインストールするには:

cd google-auth
python3 -m pip install .

cd google-auth
py -m pip install .

さらに、 pip は 開発モード でソースコードからパッケージをインストールすることができます。つまり、ソースコードを修正すると、再インストールしなくても、すぐにインストール済みのパッケージに反映されます。

python3 -m pip install --editable .

py -m pip install --editable .

バージョン管理システムからインストールする#

pip は、バージョン管理システムから直接に、パッケージをインストールすることができます。例えば、git リポジトリから直接にインストールするには:

google-auth @ git+https://github.com/GoogleCloudPlatform/google-auth-library-python.git

サポートされているバージョン管理システムや文法について、詳しくは VCS サポート の pip の説明文書を見てください。

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

もし 配布パッケージ のアーカイブ ( zip や wheel や tar ファイル) をローカルに持っているなら、 pip でそこから直接にインストールすることができます:

python3 -m pip install requests-2.18.4.tar.gz

py -m pip install requests-2.18.4.tar.gz

複数のパッケージのアーカイブを置いたディレクトリを pip に探索させるようにして、Python パッケージインデックス を全く利用しないということも可能です:

python3 -m pip install --no-index --find-links=/local/dir/ requests

py -m pip install --no-index --find-links=/local/dir/ requests

この機能は、限定的なインターネット接続しか得られないシステムでパッケージをインストールする際や、配布物パッケージの出自を厳密に管理したい時には便利です。

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

Python パッケージインデックス 以外のところからパッケージをダウンロードしたいのであれば、 --index-url オプションでできます:

python3 -m pip install --index-url http://index.example.com/simple/ SomeProject

py -m pip install --index-url http://index.example.com/simple/ SomeProject

Python パッケージインデックス と別のインデックスを同時に使いたいのであれば、 --extra-index-url オプションでできます:

python3 -m pip install --extra-index-url http://index.example.com/simple/ SomeProject

py -m pip install --extra-index-url http://index.example.com/simple/ SomeProject

パッケージを更新する#

pip に --upgrade オプションを与えるとパッケージの入れ替え更新ができます。例えば、 requests とその依存先パッケージの最新版をインストールしたいのなら:

python3 -m pip install --upgrade requests

py -m pip install --upgrade requests

requirements ファイルを使う#

パッケージをひとつひとつインストールする代わりに、pip では Requirements ファイル にすべての依存先パッケージを列挙しておくことができます。例えば、 requirements.txt を下記を含むように作成しておいて:

requests==2.18.4
google-auth==1.1.0

このファイルに書いてあるパッケージを全てインストールするようにと、 -r オプションを与えることで pip に指示します:

python3 -m pip install -r requirements.txt

py -m pip install -r requirements.txt

依存関係を凍結する#

Pip では、 freeze コマンドを使うことで、インストール済みの全パッケージのバージョン付きのリストを取り出すことができます:

python3 -m pip freeze

py -m pip freeze

それは、次に挙げるようなパッケージ指定子のリストを出力します:

cachetools==2.0.1
certifi==2017.7.27.1
chardet==3.0.4
google-auth==1.1.1
idna==2.6
pyasn1==0.3.6
pyasn1-modules==0.1.4
requests==2.18.4
rsa==3.4.2
six==1.11.0
urllib3==1.22

pip freeze コマンドは、環境内にインストール済みのすべてのパッケージの正確なバージョンを再生成することができる Requirements Files を作成するのに便利に使えます。