仮想環境

Pythonプロジェクトで作業する際には、おそらく仮想環境（または同様のメカニズム）を使用して、各プロジェクトにインストールするパッケージを分離する必要があります。

情報

仮想環境、その作成方法、使用方法を既に知っている場合は、このセクションをスキップしても構いません。🤓

ヒント

仮想環境は環境変数とは異なります。

環境変数とは、プログラムで使用できるシステム内の変数です。

仮想環境とは、いくつかのファイルを含むディレクトリです。

情報

このページでは、仮想環境の使用方法と動作方法について説明します。

すべてを管理するツール（Pythonのインストールを含む）を採用する準備ができている場合は、uvを試してみてください。

プロジェクトの作成

最初に、プロジェクト用のディレクトリを作成します。

通常、私はホーム/ユーザーディレクトリ内にcodeという名前のディレクトリを作成します。

そして、その中にプロジェクトごとに1つのディレクトリを作成します。

// Go to the home directory
$ cd
// Create a directory for all your code projects
$ mkdir code
// Enter into that code directory
$ cd code
// Create a directory for this project
$ mkdir awesome-project
// Enter into that project directory
$ cd awesome-project

仮想環境の作成

Pythonプロジェクトで初めて作業を開始する際には、プロジェクト内に仮想環境を作成します。

ヒント

これはプロジェクトごとに一度だけ行えばよく、作業するたびに実行する必要はありません。

venvuv

仮想環境を作成するには、Pythonに付属するvenvモジュールを使用できます。

$ python -m venv .venv

コマンドの意味

• python: pythonというプログラムを使用します。
• -m: スクリプトとしてモジュールを呼び出します。次にどのモジュールを使用するかを指定します。
• venv: 通常、Pythonにインストールされているvenvというモジュールを使用します。
• .venv: 新しいディレクトリ.venvに仮想環境を作成します。

uvがインストールされている場合は、それを使用して仮想環境を作成できます。

$ uv venv

ヒント

デフォルトでは、uvは.venvというディレクトリに仮想環境を作成します。

ただし、ディレクトリ名を追加の引数として渡してカスタマイズできます。

このコマンドは、.venvという名前のディレクトリに新しい仮想環境を作成します。

.venvまたはその他の名前

仮想環境は別のディレクトリに作成できますが、.venvと呼ぶのが慣例です。

仮想環境の有効化

新しい仮想環境を有効化して、実行するPythonコマンドやインストールするパッケージがそれを使用するようにします。

ヒント

プロジェクトで作業する新しいターミナルセッションを開始するたびにこれを実行します。

Linux、macOSWindows PowerShellWindows Bash

$ source .venv/bin/activate

$ .venv\Scripts\Activate.ps1

または、Windows用のBash（例：Git Bash）を使用する場合

$ source .venv/Scripts/activate

ヒント

その環境に新しいパッケージをインストールするたびに、有効化し直してください。

これにより、そのパッケージによってインストールされたターミナル（CLI）プログラムを使用する場合、グローバルにインストールされている可能性のある他のプログラム（必要なものとは異なるバージョンである可能性があります）ではなく、仮想環境からのプログラムを使用することが保証されます。

仮想環境が有効になっていることの確認

仮想環境が有効になっていることを確認します（前のコマンドが機能したことを確認します）。

ヒント

これは任意ですが、すべてが期待通りに動作しており、意図した仮想環境を使用していることを確認する良い方法です。

Linux、macOS、Windows BashWindows PowerShell

$ which python

/home/user/code/awesome-project/.venv/bin/python

プロジェクト内（この場合はawesome-project）の.venv/bin/pythonにpythonバイナリが表示された場合、正常に動作しました。🎉

$ Get-Command python

C:\Users\user\code\awesome-project\.venv\Scripts\python

プロジェクト内（この場合はawesome-project）の.venv\Scripts\pythonにpythonバイナリが表示された場合、正常に動作しました。🎉

pipのアップグレード

ヒント

uvを使用している場合、pipの代わりにそれを使用してパッケージをインストールするため、pipをアップグレードする必要はありません。😎

パッケージのインストールにpip（Pythonにデフォルトで付属）を使用している場合は、最新バージョンにアップグレードする必要があります。

パッケージのインストール中に発生する多くの予期せぬエラーは、最初にpipをアップグレードするだけで解決されます。

ヒント

通常、これは仮想環境を作成した直後、一度だけ実行します。

仮想環境がアクティブになっていることを確認し（上記のcommandを使用）、実行します。

$ python -m pip install --upgrade pip

---> 100%

.gitignoreの追加

Gitを使用している場合（使用する必要があります）、.venv内のすべてをGitから除外する.gitignoreファイルを追加します。

ヒント

uvを使用して仮想環境を作成した場合、既にこれを実行しているため、この手順をスキップできます。😎

ヒント

これは仮想環境を作成した直後、一度だけ実行します。

$ echo "*" > .venv/.gitignore

コマンドの意味

• echo "*"：ターミナルにテキスト*を「出力」します（次の部分はそれを少し変更します）。
• >：>の左側のcommandによってターミナルに出力されるものは、出力されず、代わりに>の右側のファイルに書き込まれます。
• .gitignore：テキストを書き込むファイルの名前。

そして、Gitでは*は「すべて」を意味します。そのため、.venvディレクトリ内のすべてが無視されます。

このcommandは、次の内容を持つ.gitignoreファイルを作成します。

*

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

環境をアクティブにした後、その環境にパッケージをインストールできます。

ヒント

プロジェクトに必要なパッケージをインストールまたはアップグレードする際に、一度だけ実行します。

バージョンをアップグレードするか、新しいパッケージを追加する必要がある場合は、もう一度実行します。

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

急いでいて、プロジェクトのパッケージ要件を宣言するファイルを使用したくない場合は、直接インストールできます。

ヒント

プログラムに必要なパッケージとバージョンをファイル（例：requirements.txtまたはpyproject.toml）に保存することを（非常に）お勧めします。

pipuv

$ pip install "fastapi[standard]"

---> 100%

uvをお持ちの場合

$ uv pip install "fastapi[standard]"
---> 100%

requirements.txtからのインストール

requirements.txtがある場合は、それを使用してパッケージをインストールできます。

pipuv

$ pip install -r requirements.txt
---> 100%

uvをお持ちの場合

$ uv pip install -r requirements.txt
---> 100%

requirements.txt

いくつかのパッケージを含むrequirements.txtは次のようになります。

fastapi[standard]==0.113.0
pydantic==2.8.0

プログラムの実行

仮想環境をアクティブにした後、プログラムを実行できます。すると、インストールしたパッケージを含む仮想環境内のPythonが使用されます。

$ python main.py

Hello World

エディターの設定

おそらくエディターを使用するでしょう。自動補完とインラインエラーを取得できるように、作成したのと同じ仮想環境を使用するように設定してください（おそらく自動検出されます）。

例えば

• VS Code
• PyCharm

ヒント

通常、これは仮想環境を作成する際に一度だけ実行する必要があります。

仮想環境の非アクティブ化

プロジェクトの作業が完了したら、仮想環境を非アクティブ化できます。

$ deactivate

このようにして、pythonを実行しても、そこにインストールされているパッケージを使用してその仮想環境から実行されなくなります。

作業の準備完了

これで、プロジェクトの作業を開始する準備ができました。

ヒント

上記のすべてを理解したいですか？

読み進めてください。👇🤓

仮想環境を使用する理由

FastAPIを使用するには、Pythonをインストールする必要があります。

その後、FastAPIと使用したいその他のパッケージをインストールする必要があります。

パッケージをインストールするには、通常、Pythonに付属のpipcommand（または同様の代替手段）を使用します。

しかし、pipを直接使用すると、パッケージはグローバルPython環境（Pythonのグローバルインストール）にインストールされます。

問題

では、グローバルPython環境にパッケージをインストールすることの問題は何でしょうか？

ある時点で、異なるパッケージに依存する多くの異なるプログラムを作成することになるでしょう。そして、あなたが取り組むこれらのプロジェクトの中には、同じパッケージの異なるバージョンに依存するものもあるでしょう。😱

たとえば、philosophers-stoneというプロジェクトを作成できます。このプログラムは、バージョン1を使用するharryという別のパッケージに依存しています。そのため、harryをインストールする必要があります。

flowchart LR
    stone(philosophers-stone) -->|requires| harry-1[harry v1]

その後、ある時点でprisoner-of-azkabanという別のプロジェクトを作成し、このプロジェクトもharryに依存しますが、このプロジェクトにはharryバージョン3が必要です。

flowchart LR
    azkaban(prisoner-of-azkaban) --> |requires| harry-3[harry v3]

しかし、ここで問題となるのは、ローカルの仮想環境ではなく、グローバルに（グローバル環境に）パッケージをインストールする場合、インストールするharryのバージョンを選択する必要があることです。

philosophers-stoneを実行するには、たとえば次のようにしてharryバージョン1を最初にインストールする必要があります。

$ pip install "harry==1"

そして、グローバルPython環境にharryバージョン1がインストールされます。

flowchart LR
    subgraph global[global env]
        harry-1[harry v1]
    end
    subgraph stone-project[philosophers-stone project]
        stone(philosophers-stone) -->|requires| harry-1
    end

しかし、prisoner-of-azkabanを実行する場合は、harryバージョン1をアンインストールしてharryバージョン3をインストールする必要があります（または、バージョン3をインストールすると、バージョン1が自動的にアンインストールされます）。

$ pip install "harry==3"

そして、グローバルPython環境にharryバージョン3がインストールされます。

そして、philosophers-stoneを再度実行しようとすると、harryバージョン1が必要なため、動作しない可能性があります。

flowchart LR
    subgraph global[global env]
        harry-1[<strike>harry v1</strike>]
        style harry-1 fill:#ccc,stroke-dasharray: 5 5
        harry-3[harry v3]
    end
    subgraph stone-project[philosophers-stone project]
        stone(philosophers-stone) -.-x|⛔️| harry-1
    end
    subgraph azkaban-project[prisoner-of-azkaban project]
        azkaban(prisoner-of-azkaban) --> |requires| harry-3
    end

ヒント

Pythonパッケージでは、新しいバージョンで破壊的な変更を回避するために最善を尽くすことが一般的ですが、安全を期して、新しいバージョンを意図的にインストールし、テストを実行してすべてが正しく動作することを確認する方が良いでしょう。

さて、多くの他のパッケージを、あなたのすべてのプロジェクトが依存していると想像してみてください。それは管理するのが非常に困難です。そして、おそらくいくつかのプロジェクトをパッケージの非互換なバージョンで実行することになり、何かが動作していない理由がわからなくなるでしょう。

また、オペレーティングシステム（例：Linux、Windows、macOS）によっては、既にPythonがインストールされている場合があります。そして、その場合、おそらくシステムに必要な特定のバージョンでいくつかのパッケージがプリインストールされています。グローバルPython環境にパッケージをインストールすると、オペレーティングシステムに付属していたプログラムの一部が破損する可能性があります。

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

Pythonをインストールすると、コンピューターにいくつかのファイルを含むいくつかのディレクトリが作成されます。

これらのディレクトリの中には、インストールしたすべてのパッケージを保持する役割を担っているものがあります。

実行すると

// Don't run this now, it's just an example 🤓
$ pip install "fastapi[standard]"
---> 100%

通常PyPIから、FastAPIコードを含む圧縮ファイルがダウンロードされます。

FastAPIが依存する他のパッケージのファイルもダウンロードされます。

次に、これらのファイルをすべて解凍して、コンピューターのディレクトリに配置します。

デフォルトでは、ダウンロードして解凍したファイルは、Pythonインストールに付属するディレクトリ、つまりグローバル環境に配置されます。

仮想環境とは何か

グローバル環境ですべてのパッケージを持つことの問題に対する解決策は、作業中の各プロジェクトに仮想環境を使用することです。

仮想環境は、グローバル環境と非常によく似たディレクトリであり、プロジェクトのパッケージをインストールできます。

このように、各プロジェクトは、それぞれ独自の仮想環境（.venvディレクトリ）とパッケージを持ちます。

flowchart TB
    subgraph stone-project[philosophers-stone project]
        stone(philosophers-stone) --->|requires| harry-1
        subgraph venv1[.venv]
            harry-1[harry v1]
        end
    end
    subgraph azkaban-project[prisoner-of-azkaban project]
        azkaban(prisoner-of-azkaban) --->|requires| harry-3
        subgraph venv2[.venv]
            harry-3[harry v3]
        end
    end
    stone-project ~~~ azkaban-project

仮想環境のアクティブ化とは何か

たとえば、次のようにして仮想環境をアクティブ化すると

Linux、macOSWindows PowerShellWindows Bash

$ source .venv/bin/activate

$ .venv\Scripts\Activate.ps1

または、Windows用のBash（例：Git Bash）を使用する場合

$ source .venv/Scripts/activate

このcommandは、次のcommandで使用できるいくつかの環境変数を作成または変更します。

これらの変数の1つはPATH変数です。

ヒント

PATH環境変数の詳細については、環境変数セクションを参照してください。

仮想環境のアクティブ化により、そのパス.venv/bin（LinuxおよびmacOSの場合）または.venv\Scripts（Windowsの場合）がPATH環境変数に追加されます。

環境のアクティブ化前、PATH変数は次のようになっているとします。

Linux、macOSWindows

/usr/bin:/bin:/usr/sbin:/sbin

つまり、システムはプログラムを以下のディレクトリで検索します。

• /usr/bin
• /bin
• /usr/sbin
• /sbin

C:\Windows\System32

つまり、システムはプログラムを以下のディレクトリで検索します。

• C:\Windows\System32

仮想環境を有効化すると、PATH変数は以下のようになります。

Linux、macOSWindows

/home/user/code/awesome-project/.venv/bin:/usr/bin:/bin:/usr/sbin:/sbin

つまり、システムは最初に以下のディレクトリでプログラムを検索するようになります。

/home/user/code/awesome-project/.venv/bin

その後、他のディレクトリを検索します。

そのため、ターミナルでpythonと入力すると、システムは

/home/user/code/awesome-project/.venv/bin/python

にあるPythonプログラムを見つけ、それを実行します。

C:\Users\user\code\awesome-project\.venv\Scripts;C:\Windows\System32

つまり、システムは最初に以下のディレクトリでプログラムを検索するようになります。

C:\Users\user\code\awesome-project\.venv\Scripts

その後、他のディレクトリを検索します。

そのため、ターミナルでpythonと入力すると、システムは

C:\Users\user\code\awesome-project\.venv\Scripts\python

にあるPythonプログラムを見つけ、それを実行します。

重要な点は、仮想環境のパスがPATH変数の**先頭**に追加されることです。システムは他のPython環境よりも**前に**仮想環境のPythonを見つけます。これにより、pythonを実行すると、グローバル環境などの他のpythonではなく、**仮想環境内のPython**が使用されます。

仮想環境の有効化によって他のいくつかの設定も変更されますが、これは最も重要な変更の1つです。

仮想環境の確認

例えば、

Linux、macOS、Windows BashWindows PowerShell

$ which python

/home/user/code/awesome-project/.venv/bin/python

$ Get-Command python

C:\Users\user\code\awesome-project\.venv\Scripts\python

を使用すると、使用されるpythonプログラムは**仮想環境内**のものが使用されていることを確認できます。

LinuxとmacOSではwhichコマンドを、Windows PowerShellではGet-Commandコマンドを使用します。

これらのコマンドは、PATH環境変数の**各パスを順番に**調べて、pythonというプログラムを探します。 見つかったら、そのプログラムへの**パスを表示**します。

最も重要なのは、pythonを呼び出すと、まさにその「python」が実行されることです。

したがって、正しい仮想環境にいることを確認できます。

ヒント

仮想環境を有効化し、Pythonを使用してから、別のプロジェクトに**移行**するのは簡単です。

しかし、別のプロジェクトの仮想環境のPythonを使用しているため、2つ目のプロジェクトは**動作しません**。

使用されているpythonを確認できるのは便利です。🤓

仮想環境を非アクティブ化する理由

例えば、プロジェクトphilosophers-stoneに取り組んでいて、その**仮想環境を有効化し**、パッケージをインストールしてその環境で作業しているとします。

その後、別のプロジェクトprisoner-of-azkabanで作業したいとします。

そのプロジェクトに移動します。

$ cd ~/code/prisoner-of-azkaban

philosophers-stoneの仮想環境を非アクティブ化しないと、ターミナルでpythonを実行すると、philosophers-stoneのPythonが使用されます。

$ cd ~/code/prisoner-of-azkaban

$ python main.py

// Error importing sirius, it's not installed 😱
Traceback (most recent call last):
    File "main.py", line 1, in <module>
        import sirius

しかし、philosophers-stoneの仮想環境を非アクティブ化し、prisoner-of-azkabanの新しい仮想環境を有効化すると、pythonを実行したときにprisoner-of-azkabanの仮想環境内のPythonが使用されます。

$ cd ~/code/prisoner-of-azkaban

// You don't need to be in the old directory to deactivate, you can do it wherever you are, even after going to the other project 😎
$ deactivate

// Activate the virtual environment in prisoner-of-azkaban/.venv 🚀
$ source .venv/bin/activate

// Now when you run python, it will find the package sirius installed in this virtual environment ✨
$ python main.py

I solemnly swear 🐺

代替手段

これは、開始するための簡単なガイドであり、すべてがどのように**動作するか**を学ぶためのものです。

仮想環境、パッケージ依存関係（要件）、プロジェクトを管理するための多くの**代替手段**があります。

準備ができたら、プロジェクト全体、パッケージの依存関係、仮想環境などを管理するためのツールを使用したい場合は、uvを試してみることをお勧めします。

uvは多くのことができます。例えば、

• 様々なバージョンを含む**Pythonのインストール**
• プロジェクトの**仮想環境**の管理
• **パッケージ**のインストール
• プロジェクトのパッケージ**依存関係とバージョン**の管理
• 依存関係を含む正確なパッケージとバージョンをインストールできるようにし、開発中のコンピューターと同じように本番環境でもプロジェクトを実行できることを確認します。これは**ロック**と呼ばれます。
• そして、他にも多くのことができます。

結論

これを読解して理解できたなら、多くの開発者よりも仮想環境について**はるかに詳しくなりました**。🤓

これらの詳細を知ることは、複雑に見える問題のデバッグを行う際に役立ちます。なぜなら、その**内部の動作**を理解しているからです。😎