bitBuyerプロジェクトとPython開発における仮想環境の重要性

Hey there!😉

bitBuyerプロジェクトのような開発に参加する場合、それぞれのプロジェクトに適したPythonのバージョンやライブラリのバージョンを使う必要があります。しかし、パソコン上で複数のプロジェクトを並行して進めていると、ライブラリの競合やバージョンの衝突が起きがちです。

そこで活躍するのが「仮想環境」です。仮想環境を使うことで、他のプロジェクトやグローバル環境に影響を与えることなく、必要な依存関係をクリーンに管理できます。プロジェクトごとに独立したPython環境を構築できるため、開発の自由度と安定性が格段に向上します。

グローバル環境とは？

Pythonをインストールした直後に使える状態、つまりシステム全体で共有されるPythonの実行環境のことを「グローバル環境」と呼びます。たとえば、pip installコマンドで何かをインストールしたときに、それがどのプロジェクトからも見える状態になっている場合、それはグローバル環境で作業しているということです。

このグローバル環境を直接使って開発を進めることもできますが、複数のプロジェクトで異なるライブラリやバージョンが必要になると、ライブラリ同士の競合や予期しないエラーが頻発するようになります。結果として、プロジェクトが壊れたり、思わぬ不具合に悩まされることも。

そんなトラブルを避けるために、グローバル環境とは別に「隔離された」専用のPython環境（＝仮想環境）を作ることが、Python開発における基本的な作法になっています。

仮想環境とは？

Pythonの仮想環境とは、あなたのプロジェクト専用に切り分けられたPythonの作業スペースのことです。

通常、Pythonのライブラリは「グローバル環境」と呼ばれる、パソコン全体で共有される場所にインストールされます。たとえばpip installでインストールしたライブラリは、すべてのプロジェクトから見える状態になります。

一見便利に思えますが、開発が進んでいくとこうした声が出てきます。

「こっちのプロジェクトではこのバージョンを使いたいけど、自分のパソコンに入ってるのはもっと新しい or 古い！」
「別のプロジェクトでインストールしたライブラリの影響で、なんかこっちの動作がおかしい……」
「せっかく動くようにしたのに、他の作業をしたら壊れた！ なんで！？」

こうしたトラブルの原因は、全てのプロジェクトが同じ環境（グローバル環境）を共有していることにあります。つまり、Pythonやライブラリのバージョンが混在し、互いに干渉してしまうのです。

仮想環境がなぜ必要か

仮想環境を使うことで、こうしたバージョンの衝突を避けられます。
具体的には、プロジェクトごとに独立したPython環境を作成し、その中に必要なライブラリだけをインストールして使うことができます。

これにより、

• 他のプロジェクトに影響を与えずに作業できる
• 動作が「いつの間にか変わる」といった現象が起きにくくなる
• 「このプロジェクトではこのバージョンを使う」と明確に管理できる

といったメリットがあります。

なお、仮想環境はPython本体をまるごとコピーするわけではなく、既存のPythonをベースにしつつ、ライブラリの保存場所や動作環境を切り替える仕組みになっています。
そのため、パソコン上には複数の仮想環境を共存させることができ、それぞれが「自分だけの世界」として機能します。

仮想環境の種類

仮想環境を構築するためのツールは複数存在します。
その中でもPython 3が標準搭載しているツールは「venv」と言います。
以下はChatGPTで作成した、仮想環境を構築するためのツール一覧です！

venvを使った仮想環境の構築

仮想環境を作る方法には、venvの他にもvirtualenvやcondaなどがありますが、この記事ではあえてvenvを使います。

その理由はシンプルで、venvはPythonに標準で含まれている機能だからです。追加のインストールも不要で、ほとんどの環境でそのまま使えます。シンプルな構成で管理しやすく、bitBuyerプロジェクトのように、将来的にAIモデルのトレーニングやオンライン機械学習などの高度な処理を取り込む構想がある場合でも、最初の環境構築としてはvenvが非常に扱いやすく、柔軟性にも優れています。

それでは、まずvenvがインストールされているか確認してみましょう。
コマンドプロントやターミナルを開いて以下のコマンドを入力します。

python -m venv --help

ヘルプメッセージが表示されている場合はvenvがインストールされてます！
もしDebian系のLinux OS（Ubuntuなど）の場合で利用できない場合は、

sudo apt-get install python3-venv

のコマンドでインストールできる場合があります 。

次に仮想環境を構築したいディレクトリ（フォルダ）へ移動します。

cd 移動したいディレクトリのファイルパス

移動できたら、いよいよ仮想環境を作成するコマンドを打ち込みます。

python -m venv <仮想環境名>

<仮想環境名>のところは好きな名前を打ち込みます。
一般的にはvenvまたはenvといった名前が使われます。
ここではvenvという名前を使って仮想環境を構築します。

📌なぜ「venv」や「env」という名前がよく使われるの？

venvは「virtual environment（仮想環境）」の略で、Python公式のモジュール名そのものでもあります。一方、envはより汎用的な略称で、「environment（環境）」を指します。どちらも「ここに開発用の仮想環境があるよ」という意味が一目でわかる名前として、多くのプロジェクトで使われています。

もちろん、名前は自由なので、プロジェクト名を付けても問題ありませんが、他の人が見たときにも分かりやすく、慣習的にも親しまれているのがvenvやenvです。

python -m venv venv

上記のコマンドを実行すると、cdで選択したディレクトリに指定した名前のディレクトリ（この例ではvenv）が作成されます。
このディレクトリの中には、Pythonインタプリタのコピー、pip、そして仮想環境を動作させるために必要なその他のファイルが含まれています 。  

なお、「python -m venv」というコマンドの中にある「-m」は、「Pythonにvenvという機能を使ってね」と伝えるためのスイッチのようなものです。

Pythonにはvenvという「仮想環境を作るための仕組み」が最初から備わっていて、「-m」を使うことでその仕組みを呼び出しています。

これは少し専門的に言うと「モジュールを直接実行する」やり方なのですが、いまの段階では「Pythonに “venvやって” と伝えてるだけ」と理解しておけばOKです。

次に仮想環境をアクティベートします。
アクティベートするためのコマンドは、使用しているオペレーティングシステムによって異なります。
以下はOSごとにコマンドをまとめたものです。

オペレーティングシステム	シェル	アクティベーションコマンド	ディアクティベーションコマンド
Windows	コマンドプロンプト	<仮想環境名>\Scripts\activate	deactivate
Windows	PowerShell	.\<仮想環境名>\Scripts\Activate.ps1	deactivate
macOS/Linux	Bash/Zsh	source <仮想環境名>/bin/activateまたは.<仮想環境名>/bin/activate	deactivate
macOS/Linux	Fish	source <仮想環境名>/bin/activate.fish	deactivate
macOS/Linux	PowerShell	<仮想環境名>/Scripts/Activate.ps1	deactivate

実行して現在のディレクトリの前に、仮想環境の名前（ここではvenv）が表示されたら成功です。

仮想環境での作業が終了したら、それをディアクティベート（非アクティブ化）することができます。ディアクティベートするには、どのオペレーティングシステムでも共通して、ターミナルにdeactivateと入力して実行します 。
ディアクティベートすると、プロンプトの先頭に表示されていた仮想環境の名前が消え、元の状態に戻ります。

仮想環境を構築したらpipを使用して適切なライブラリをインストールします。
前回のおさらいです！

pip install <パッケージ名>

というコマンドを実行します。
例えば、requestsというライブラリをインストールしたい場合は、

pip install requests

と入力して実行します 。

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

pip install <パッケージ名>==<バージョン番号>

のようにバージョン番号を指定します

例：

pip install requests==2.25.1

パッケージをアップグレードしたい場合は、

pip install --upgrade <パッケージ名>

を使用します 。

VS Codeを使った簡単な仮想環境の実行方法

ここまで、コマンドプロンプトやターミナルを使って仮想環境を手動でアクティベート・ディアクティベートする方法をご紹介してきました。

ですが、Visual Studio Code（VS Code）を使っている場合は、実はもっと簡単に仮想環境を使うことができます！

VS Codeには、Pythonスクリプトを実行するときに、自動的に仮想環境を選んでくれる機能が備わっています。この機能を使えば、仮想環境を毎回手動で有効化しなくても、スクリプトを実行するだけで、指定した仮想環境が裏で自動的に使われるようになります。

✅仮想環境をVS Codeで指定する方法

1. VS Codeで、仮想環境を作成したプロジェクトフォルダを開きます。
2. 左下のステータスバーに表示されているPythonのバージョンをクリックします。
3. 「インタープリタの選択」ウィンドウが開いたら、作成した仮想環境（例：./venv/bin/pythonや.\venv\Scripts\python.exe）を選択します。

選択が完了すると、.vscode/settings.jsonファイルに次のような設定が自動で追加されます：

{
  "python.pythonPath": "venv/bin/python"  // Windowsなら「Scripts/python.exe」
}

これで、VS Code上で実行するPythonスクリプトはすべてこの仮想環境を使うようになります。

⚠️仮想環境が認識されないときは？

VS Codeが自動で仮想環境を検出できない場合もあります。そんなときは、以下を確認してみてください。

1. 仮想環境がプロジェクト内にあるか？

仮想環境のディレクトリ（例：venv/）が、プロジェクトフォルダの直下にあると、VS Codeは自動的に検出しやすくなります。フォルダが深い階層にあると見つけにくくなることがあります。

2. .vscode/settings.jsonを手動で編集する

自動で反映されない場合は、以下のように自分でファイルを作成・修正することで、仮想環境のパスを直接指定できます：

{
  "python.pythonPath": "./venv/bin/python"  // Mac/Linux の場合
}

{
  "python.pythonPath": ".\\venv\\Scripts\\python.exe"  // Windows の場合
}

3. Python拡張機能が入っているか確認する

VS Codeのマーケットプレイスから「Python」と検索し、Microsoft公式の拡張機能がインストールされているか確認してください。これがないとインタープリタの選択ができません。

4. VS Codeを再起動する

仮想環境を作成した直後は、VS Codeが環境の存在にまだ気づいていないことがあります。再起動すると認識されることがあります。

💡VS Codeまとめ

仮想環境を手動で使う方法を知っておくことは大切ですが、日常的な開発では、VS Codeのインタープリタ設定を活用することで作業が格段にスムーズになります。
bitBuyerプロジェクトのように今後AIや自動化が関わってくるような開発でも、開発環境の構築がストレスなく行えることは非常に重要です。

ちょっとした設定で、仮想環境が “空気のようにそこにある” 状態をつくっていきましょう。

requirements.txtを使った依存関係の管理

プロジェクトで使っているPythonのライブラリ（パッケージ）とそのバージョンを記録・共有するために、requirements.txtという専用ファイルを使うのが一般的です。

これは、Pythonのプロジェクトにおける「依存関係のリスト」のようなもので、以下のような目的で使われます：

• 他の開発者が同じ環境を再現しやすくなる（再現性）
• 仮想環境を初期化するときに一発で必要なものをまとめてインストールできる
• プロジェクトがどんなライブラリに依存しているかが明確になる

✅requirements.txt、どうやって作るの？

まず、仮想環境をアクティベートした状態で、プロジェクトに必要なライブラリをすべてインストールします。その後、以下のコマンドを使ってrequirements.txtを作成します：

pip freeze > requirements.txt

ここで使われている「pip freeze」は、現在の仮想環境にインストールされているすべてのライブラリとそのバージョンを一覧表示するコマンドです。

その後の「>」は、表示された内容を「画面に出す」のではなく、ファイルに保存するための記号です。これは「リダイレクト」と呼ばれる仕組みですが、ここでは単に「requirements.txtという名前で保存してくれる」くらいに思っておいて大丈夫です😊

💻補足：どこでこのコマンドを実行するの？

どの環境でもOKですが、初心者の方はVS Code内のターミナルを使うのが一番おすすめです。以下のいずれかの方法で大丈夫です：

• VS Codeのターミナル（メニュー「表示」→「ターミナル」）
• Windowsのコマンドプロンプト
• Macのターミナル

ただし、コマンドを実行するディレクトリ（フォルダ）は、プロジェクトフォルダの中であることを確認してください。そうしないと、requirements.txtが見当はずれの場所に作られてしまうことがあります。

🧠依存関係の管理まとめ

requirements.txtを使って依存関係を明示しておくと、自分にとっても、将来の自分や他の開発者にとっても、プロジェクトの扱いやすさがグッと上がります。

特にbitBuyerプロジェクトのように長期的に発展していくOSSプロジェクトでは、こうした依存関係の記録が信頼性にもつながります。

Pipenvを使った仮想環境の構築

Pipenvは、Pythonの仮想環境の作成と依存関係の管理を一つのツールでまとめて行える便利なツールです。仮想環境の構築とrequirements.txtのような依存関係の記録を同時に行えるため、Pythonプロジェクトの管理をよりスッキリさせたい人に人気があります。

🗂PipfileとPipfile.lockって何？

Pipenvを使うと、プロジェクトフォルダに以下の2つのファイルが自動的に作成されます：

• Pipfile
  →プロジェクトに直接必要なライブラリとPythonのバージョンを記述します。人間が読みやすく、手動で編集もしやすい形式です。
• Pipfile.lock
  →Pipfileに書かれたライブラリが依存している “そのまた依存先” まで含め、すべてのバージョンを正確に固定します。これにより、他の開発者の環境でもまったく同じセットアップを再現できるようになります。

🎯こんな人におすすめ

• 依存関係の管理をpip installやrequirements.txtよりもっとスマートに行いたい人
• チーム開発やOSSプロジェクトで高い再現性を求めたい人
• プロジェクトのPythonバージョンも一緒に管理したい人（[requires] python_version = "3.11"などが書けます）

💡注意点

• PipenvはPythonの標準機能ではないため、初回はpip install pipenvが必要です。
• 仮想環境の構築先がOSや設定によって異なる（ディレクトリ外に作られることもある）ため、初心者は少し戸惑うかもしれません。

📌Pipenvを使う手順

以下の方法でインストールします。

Windowsの場合：

pip install --user pipenv

macOS/Linuxの場合：

pip3 install --user pipenv

また以下のコマンドでインストールができたか確認できます。

pipenv --version

さらに以下のコマンドでPipfileとPipfile.lockという2つのファイルが作成されます。

pipenv install

Pipenvで作成した仮想環境をアクティベート（有効化）するには、以下のコマンドを使用します。

pipenv shell

アクティブな仮想環境にパッケージをインストールするには、「pipenv install <パッケージ名>」という構文を使用します。例えば、人気の高いrequestsライブラリをインストールするには、以下のコマンドを実行します。

pipenv install requests

特定のバージョンのパッケージをインストールしたい場合は、「pipenv install <パッケージ名>==<バージョン番号>」という構文を使用します。

pipenv install requests==2.18.4

他にも、「>=」、「<=」、「>」、「<」、「~=（互換性のあるリリース）」などの一般的なバージョン指定子を使用することもできます 。

ところで、実際に開発を始めると「アプリ本体とは関係ないけれど、開発のために入れておきたいパッケージ」が出てきます。

たとえば、

• テスト用のツール（pytestなど）
• コードの書き方をチェックするリンター（flake8など）
• コードの見た目を整えるフォーマッター（blackなど）

といったものです。

こうしたパッケージは、アプリケーションを実際に動かすとき（＝本番環境やユーザーの手元）には必要ないものですが、開発時にはとても役立つ “作業用のツール” です。

Pipenvでは、こうした「開発専用」のパッケージを区別してインストールすることができます。

方法はとても簡単で、「pipenv install」に「--dev」フラグをつけるだけです：

pipenv install --dev pytest

こうすると、pytestは開発者用としてPipfileに記録されるため、後から環境を再構築する際にも自動的にインストールされますが、本番環境にそれが影響することはありません。

PipfileとPipfile.lockの役割と構造

ここでは、Pipenvが自動的に作成する2つのファイル──「Pipfile」と「Pipfile.lock」──について、実際の内容とともに詳しく見ていきます。

📄Pipfile：人が読む設計図

Pipfileは、プロジェクトで必要なライブラリやPythonのバージョンなど、基本的な依存関係を人間が編集しやすい形式で記述するファイルです。
従来のrequirements.txtに代わる存在であり、より構造的で可読性が高く、機能も豊富になっています。

例：シンプルなPipfileの内容

[[source]]
url = "https://pypi.org/simple"
verify_ssl = true
name = "pypi"

[packages]
requests = "*"
flask = ">=1.0.0"

[dev-packages]
pytest = "*"
flake8 = "*"

[requires]
python_version = "3.8"

• [[source]]：パッケージを取得する元（通常はPyPI）
• [packages]：アプリの実行に必要なライブラリ（依存関係）
• [dev-packages]：テストやコードチェックなど、開発時だけ使うライブラリ
• [requires]：このプロジェクトが想定しているPythonのバージョン

このように、Pipfileはプロジェクトをセットアップする上での「設計図」のような役割を果たします。

🔒Pipfile.lock：正確さと安全性を保証するレシピ

一方で、Pipfile.lockはPipenvによって「pipenv install」実行時に自動生成されるファイルで、こちらはコンピュータのための “正確なレシピ” です。

このファイルには、次のような情報が詳細に記録されています：

• Pipfileに記述されたライブラリだけでなく、それらが依存しているライブラリ（間接依存）もすべて含む
• 各ライブラリの正確なバージョン
• ダウンロード時のハッシュ値（ファイルの完全性を検証する指紋のようなもの）

これにより、Pipfile.lockは開発者全員が同じ環境で開発を再現できること（再現性）を保証します。

さらに、記録されたハッシュ値は、Pipenvによってパッケージの整合性チェックに使われます。これによって、不正なコードの混入や改ざんからプロジェクトを守ることができ、セキュリティ面でも重要な役割を果たします。

✋Pipfile.lockは手動で編集しない！

Pipfile.lockはPipenvによって完全に管理されており、手で編集するべきではありません。
依存関係を追加・削除・更新したい場合は、Pipfileを編集してから、以下のコマンドを実行します：

pipenv install      # 依存関係のインストールとPipfile.lockの更新
pipenv update       # ロックファイルを更新しながらアップグレード

✅PipfileとPipfile.lockまとめ

• Pipfileは人間が読む：何を使うかを定義
• Pipfile.lockは機械が使う：正確なバージョンと安全性を保証
• 両者がセットであることで、柔軟性と再現性を両立できる

bitBuyerプロジェクトのように、長期的な開発や将来的な自動化・AI統合を見据えるプロジェクトでは、こうした構成管理が重要になってきます。
環境の揺らぎを防ぎ、安定した開発体験を維持するためにも、Pipenvとそのファイル構成を正しく理解しておくと安心です。
Cheers!🎉