仮想環境¶
Python プロジェクトで作業する場合、各プロジェクトにインストールするパッケージを分離するために、おそらく仮想環境 (または同様のメカニズム) を使用する必要があります。
情報
仮想環境について、その作成方法と使用方法をすでに知っている場合は、このセクションをスキップしてもかまいません。🤓
ヒント
仮想環境は環境変数とは異なります。
環境変数は、プログラムで使用できるシステム内の変数です。
仮想環境は、いくつかのファイルを含むディレクトリです。
プロジェクトを作成する¶
まず、プロジェクト用のディレクトリを作成します。
私が通常行うのは、ホーム/ユーザーディレクトリ内に `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 プロジェクトに初めて取り組むときは、プロジェクト内に仮想環境を作成します。
ヒント
これはプロジェクトごとに一度だけ行う必要があり、作業するたびに行う必要はありません。
仮想環境を作成するには、Python に付属の venv モジュールを使用できます。
$ python -m venv .venv
そのコマンドの意味
python:pythonというプログラムを使用する-m: モジュールをスクリプトとして呼び出す。次にどのモジュールかを指定するvenv: 通常 Python にインストールされているvenvというモジュールを使用する.venv: 新しいディレクトリ.venvに仮想環境を作成する
uv をインストールしている場合は、それを使用して仮想環境を作成できます。
$ uv venv
ヒント
デフォルトでは、uv は .venv というディレクトリに仮想環境を作成します。
ただし、ディレクトリ名で追加の引数を渡すことでカスタマイズできます。
そのコマンドは、.venv というディレクトリに新しい仮想環境を作成します。
.venv またはその他の名前
仮想環境を別のディレクトリに作成することもできますが、.venv と呼ぶのが慣例です。
仮想環境をアクティベートする¶
新しい仮想環境をアクティベートして、実行する Python コマンドやインストールするパッケージがその環境を使用するようにします。
ヒント
プロジェクトで作業するために新しいターミナルセッションを開始するたびにこれを行います。
$ source .venv/bin/activate
$ .venv\Scripts\Activate.ps1
または、Windows 用 Bash (例: Git Bash) を使用している場合
$ source .venv/Scripts/activate
ヒント
その環境に新しいパッケージをインストールするたびに、環境を再度アクティベートしてください。
これにより、そのパッケージによってインストールされたターミナル (CLI) プログラムを使用する場合、仮想環境のものが使用され、グローバルにインストールされている可能性のある他のもの (おそらく必要なバージョンとは異なる) が使用されないようにします。
仮想環境がアクティブであることを確認する¶
仮想環境がアクティブであることを確認します（前のコマンドが機能しました）。
ヒント
これは任意ですが、すべてが期待どおりに機能しているか、意図した仮想環境を使用しているかを確認する良い方法です。
$ 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 をアップグレードするだけで解決されます。
ヒント
これは通常、仮想環境を作成した直後に一度だけ行います。
仮想環境がアクティブであることを確認し (上記のコマンドで)、次のコマンドを実行します。
$ python -m pip install --upgrade pip
---> 100%
.gitignore を追加する¶
Git を使用している場合 (使用すべきです)、.venv 内のすべてを Git から除外するために .gitignore ファイルを追加します。
ヒント
uv を使用して仮想環境を作成した場合は、すでにこれが行われているため、この手順はスキップできます。😎
ヒント
これは、仮想環境を作成した直後に一度だけ行います。
$ echo "*" > .venv/.gitignore
そのコマンドの意味
echo "*": ターミナルにテキスト*を「出力」します（次の部分はそれを少し変更します）>:>の左側にあるコマンドによってターミナルに出力されたものは、出力されずに>の右側にあるファイルに書き込まれるべきです。.gitignore: テキストを書き込むファイルの名前
そして、Gitにとっての * は「すべて」を意味します。つまり、.venv ディレクトリ内のすべてを無視します。
そのコマンドは、次の内容を持つ .gitignore ファイルを作成します。
*
パッケージをインストールする¶
環境をアクティベートした後、そこにパッケージをインストールできます。
ヒント
プロジェクトが必要とするパッケージをインストールまたはアップグレードするときは、これを一度だけ行います。
バージョンをアップグレードしたり、新しいパッケージを追加したりする必要がある場合は、再度これを行います。
パッケージを直接インストールする¶
急いでいて、プロジェクトのパッケージ要件を宣言するファイルを使用したくない場合は、それらを直接インストールできます。
ヒント
プログラムが必要とするパッケージとバージョンをファイル（たとえば requirements.txt または pyproject.toml）に入れることは、（非常に）良い考えです。
$ pip install "fastapi[standard]"
---> 100%
uv がある場合
$ uv pip install "fastapi[standard]"
---> 100%
requirements.txt からインストールする¶
requirements.txt がある場合は、それを使用してパッケージをインストールできます。
$ 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
エディタを設定する¶
おそらくエディタを使用するので、オートコンプリートとインラインエラーを取得できるように、作成した仮想環境を使用するように設定してください (おそらく自動検出されます)。
例えば
ヒント
通常、これは仮想環境を作成するときに一度だけ行えばよいでしょう。
仮想環境を非アクティベートする¶
プロジェクトでの作業が完了したら、仮想環境を非アクティベートできます。
$ deactivate
これにより、python を実行しても、そこにインストールされているパッケージを使用してその仮想環境から実行しようとはしません。
作業の準備ができた¶
これでプロジェクトの作業を開始する準備ができました。
ヒント
上記のすべてを理解したいですか？
読み続けてください。👇🤓
なぜ仮想環境を使うのか¶
FastAPI を使用するには、Python をインストールする必要があります。
その後、FastAPI と使用したい他のパッケージをインストールする必要があります。
パッケージをインストールするには、通常、Python に付属の pip コマンド (または同様の代替手段) を使用します。
しかし、pip を直接使用するだけでは、パッケージはグローバルな Python 環境 (Python のグローバルインストール) にインストールされます。
問題¶
では、グローバルな Python 環境にパッケージをインストールすることの何が問題なのでしょうか？
ある時点で、おそらく異なるパッケージに依存する多くの異なるプログラムを作成することになるでしょう。そして、作業するこれらのプロジェクトの中には、同じパッケージの異なるバージョンに依存するものもあるでしょう。😱
たとえば、`philosophers-stone` というプロジェクトを作成し、このプログラムは`harry` バージョン `1`という別のパッケージに依存しているとします。したがって、`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 パッケージでは、新しいバージョンでの破壊的な変更を避けるために最善を尽くすのが一般的ですが、安全策をとり、意図的に新しいバージョンをインストールし、すべての動作が正しいことを確認するためにテストを実行できるときにそうする方が良いでしょう。
さて、あなたのプロジェクトすべてが依存する、他の多くのパッケージでそれが起こると想像してみてください。それは管理が非常に困難です。そして、おそらくいくつかの互換性のないバージョンのパッケージでプロジェクトを実行することになり、何が機能しないのかわからないままになるでしょう。
また、OS (Linux、Windows、macOS など)によっては、Python がすでにインストールされている場合があります。その場合、システムが必要とする特定のバージョンのパッケージがいくつかプリインストールされている可能性があります。グローバルな Python 環境にパッケージをインストールすると、OS に付属のプログラムのいくつかを壊してしまう可能性があります。
パッケージはどこにインストールされるのか¶
Python をインストールすると、コンピュータにいくつかのファイルを含むディレクトリが作成されます。
これらのディレクトリの一部は、インストールするすべてのパッケージを保持する役割を担っています。
あなたが実行するとき
// Don't run this now, it's just an example 🤓
$ pip install "fastapi[standard]"
---> 100%
FastAPI のコードを含む圧縮ファイルは、通常 PyPI からダウンロードされます。
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仮想環境をアクティベートするとはどういう意味か¶
仮想環境をアクティベートするとき、例えば
$ source .venv/bin/activate
$ .venv\Scripts\Activate.ps1
または、Windows 用 Bash (例: Git Bash) を使用している場合
$ source .venv/Scripts/activate
そのコマンドは、次のコマンドで利用可能になるいくつかの環境変数を作成または変更します。
これらの変数の1つは`PATH`変数です。
ヒント
PATH 環境変数については、環境変数のセクションで詳しく学ぶことができます。
仮想環境をアクティベートすると、そのパス .venv/bin (Linux および macOS の場合) または .venv\Scripts (Windows の場合) が PATH 環境変数に追加されます。
環境をアクティベートする前の PATH 変数は次のようになっていたとします。
/usr/bin:/bin:/usr/sbin:/sbin
つまり、システムはプログラムを次の場所で検索します。
/usr/bin/bin/usr/sbin/sbin
C:\Windows\System32
つまり、システムはプログラムを次の場所で検索します。
C:\Windows\System32
仮想環境をアクティベートした後、PATH 変数は次のようになります。
/home/user/code/awesome-project/.venv/bin:/usr/bin:/bin:/usr/sbin:/sbin
つまり、システムはまず次の場所でプログラムを検索し始めます。
/home/user/code/awesome-project/.venv/bin
他のディレクトリを検索する前に。
したがって、ターミナルで `python` と入力すると、システムは次の場所で Python プログラムを見つけます。
/home/user/code/awesome-project/.venv/bin/python
そしてそれを使用します。
C:\Users\user\code\awesome-project\.venv\Scripts;C:\Windows\System32
つまり、システムはまず次の場所でプログラムを検索し始めます。
C:\Users\user\code\awesome-project\.venv\Scripts
他のディレクトリを検索する前に。
したがって、ターミナルで `python` と入力すると、システムは次の場所で Python プログラムを見つけます。
C:\Users\user\code\awesome-project\.venv\Scripts\python
そしてそれを使用します。
重要な詳細は、仮想環境のパスを PATH 変数の先頭に配置することです。システムは、他の利用可能な Python を見つける前にそれを見つけます。このようにして、python を実行すると、他の python (たとえば、グローバル環境の python) の代わりに、仮想環境の Python が使用されます。
仮想環境をアクティベートすると、他にもいくつかのことが変更されますが、これは最も重要なことの1つです。
仮想環境の確認¶
仮想環境がアクティブかどうかを確認するとき、例えば、
$ 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 を取得し、それから別のプロジェクトに移動するのは簡単です。
そして、2番目のプロジェクトは、別のプロジェクトの仮想環境から誤ったPythonを使用しているため、動作しないでしょう。
どの `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
しかし、仮想環境を非アクティベートして `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 を含め、様々なバージョンの Python をインストールできます。
- プロジェクトの仮想環境を管理できます。
- パッケージをインストールできます。
- プロジェクトのパッケージ依存関係とバージョンを管理します。
- 依存関係を含め、正確なパッケージとバージョンのセットをインストールすることを保証し、開発中のコンピューターとまったく同じように本番環境でプロジェクトを実行できることを確実にします。これはロッキングと呼ばれます。
- その他多くのこと
結論¶
これをすべて読み、理解したあなたは、そこらの多くの開発者よりも仮想環境についてはるかに多くのことを知っています。🤓
これらの詳細を知っていることは、複雑に思える何かをデバッグするときに将来役立つ可能性が非常に高く、そのすべてが内部でどのように機能するかを知っているでしょう。😎