[Clinical AI Coding 100 : C30.4] 仮想環境入門──venvで「清潔野」を守る

---

Clinical AI Coding 100へようこそ。このシリーズでは、医療従事者や研究者の皆様が、AI技術を自らの手で実装し、臨床や研究の現場で活用するための実践的な知識を学んでいきます。

前回（C30.3）では、Jupyter Notebookでの実験的なコードを、VS Codeを用いて再現可能で堅牢な「本番志向」のコードへと昇格させる方法を学びました。しかし、高品質なコードを書くだけでは、医療AIプロジェクトの「安全性」と「再現性」は担保できません。

今回は、医療AI開発プロジェクトの全ての基盤となる、最も重要な概念の一つである「仮想環境（Virtual Environment）」について学びます。特に、Pythonに標準で搭載されている「venv」という仕組みに焦点を当てます。

---

医療現場のアナロジー：「清潔野」としての仮想環境

医療現場において、我々は手術の際に厳格な「清潔野（Clean Zone）」を確保します。これは、外部からの汚染を防ぎ、患者の安全を守るための絶対的なルールです。

Pythonを使ったAI開発における「仮想環境」も、この清潔野と全く同じ役割を果たします。

なぜ「清潔野」が必要なのか？

AI開発では、pandas（データ解析）、scikit-learn（機械学習）、PyTorch（深層学習）など、多くの外部ライブラリ（専門家が作成したツールセット）を利用します。問題は、これらのライブラリが「バージョン」に依存し、互いに複雑な「依存関係」を持つことです。

これを臨床現場の「薬剤」に例えてみましょう。

1. グローバル環境（汚染区域）
   • 仮想環境を使わずにPC本体（OS）に直接ライブラリをインストールすることは、病院の「中央薬剤部」の棚に、全ての患者さん向けの薬を裸で置くようなものです。
2. 依存関係コンフリクト（薬物相互作用）
   • プロジェクトA（論文解析）では、「ワルファリン（古いバージョンのpandas 1.5）」が必要だとします。
   • プロジェクトB（新規AI開発）では、「DOAC（新しいバージョンのpandas 2.2）」が必要だとします。
   • もし、中央薬剤部の棚で「ワルファリン」を「DOAC」に置き換えてしまうと、プロジェクトAは「薬が違う」というエラーで動くなくなります。これが「依存関係コンフL クト」です。

この問題を放置すると、過去の研究（コード）の再現性が失われ、新しいプロジェクトの環境構築も困難になります。これは、医療研究において許容できる状態ではありません (Stodden et al. 2018)。

venvによる解決策：「患者ごとの無菌トレイ」

仮想環境（venv）は、プロジェクトごとに完全に隔離された「Pythonの実行環境」を作成する技術です。

これは、手術ごとに用意される「滅菌された無菌トレイ」や、患者ごとに用意される「処方箋に基づいた薬剤トレイ」に相当します。

• プロジェクトA用のトレイ（仮想環境A）には、「ワルファリン（pandas 1.5）」だけを置きます。
• プロジェクトB用のトレイ（仮想環境B）には、「DOAC（pandas 2.2）」だけを置きます。

これらは互いに一切干渉しないため、両方のプロジェクトを安全かつ独立して管理できます。これが、現代のソフトウェア開発、特に科学技術計算において仮想環境が必須とされる理由です (Wilson et al. 2014)。

---

Python標準「venv」の実践ガイド

venvは、Python 3.3以降に標準で搭載されている仮想環境管理ツールです。追加のインストールが不要で軽量なため、最も基本的な「清潔野」確保の手段として広く使われています (Python Software Foundation 2025a)。

ステップ1：仮想環境（清潔野）の作成

まず、プロジェクト用のフォルダ（例：clinical_ai_project）を作成し、その中で作業を行います。

# プロジェクト用のフォルダを作成
mkdir clinical_ai_project

# 作成したフォルダに移動
cd clinical_ai_project

次に、このフォルダ内に .venv という名前の仮想環境（清潔野）を作成します。

# 'python -m venv <環境名>' コマンドを実行
# .venv という名前（慣習）で仮想環境を作成します
python -m venv .venv

• python -m venv は、Pythonの venv モジュールを実行するという意味です。
• .venv は作成される仮想環境が格納されるフォルダ名です。先頭にドット.をつけるのは、隠しフォルダとして扱われやすく、VS Codeなどのツールが自動認識しやすいため、一般的な慣習となっています。

実行すると、clinical_ai_project フォルダ内に .venv フォルダが作成されます。この中に、隔離されたPython実行環境一式が格納されます。

ステップ2：仮想環境の有効化（清潔野への入室）

仮想環境は、作成しただけでは使えません。「有効化（Activate）」することで、その「清潔野」に入室できます。

実行するコマンドはOSによって異なります。

▼ Windows (PowerShellの場合)

# .\.venv\Scripts\Activate.ps1 を実行
.\.venv\Scripts\Activate.ps1

(注: もし実行ポリシーエラーが出る場合は、Set-ExecutionPolicy RemoteSigned -Scope Process を実行してから再度試してください)

▼ Windows (コマンドプロンプトの場合)

# .\.venv\Scripts\activate.bat を実行
.\.venv\Scripts\activate.bat

▼ macOS / Linux (bash/zsh の場合)

# source .venv/bin/activate を実行
source .venv/bin/activate

正しく有効化されると、ターミナル（コマンドプロンプト）の行頭に (.venv) のような表示が追加されます。これは、現在「清潔野」に入室していることを示す目印です。

# (例：macOSやLinux)
(.venv) $ 

ステップ3：ライブラリのインストール（器具の準備）

「清潔野」に入室した状態で pip install を実行すると、ライブラリはPC本体（グローバル環境）ではなく、この .venv の中にだけインストールされます。

# (必ず (.venv) が表示されていることを確認)

# pip自体を最新版に更新します
pip install --upgrade pip

# pandas と scikit-learn をこの環境にインストール
pip install pandas scikit-learn

# インストールされたライブラリ一覧を確認
pip list

pip list を実行すると、グローバル環境とは異なり、今インストールしたライブラリだけ（と、それらが依存する最小限のライブラリ）が表示されるはずです。

ステップ4：仮想環境の無効化（清潔野からの退出）

作業が終わったら、「清潔野」から退出します。

# (必ず (.venv) が表示されていることを確認)

# deactivate と入力して実行
deactivate

実行すると、行頭の (.venv) が消え、元のグローバル環境に戻ったことがわかります。

---

再現性の鍵：「処方箋」としての requirements.txt

仮想環境によって、自分のPC内での「薬物相互作用」は防げました。しかし、この研究（コード）を同僚や、未来の自分、あるいは論文の査読者と共有する場合はどうでしょうか？

口頭で「pandasとscikit-learnを使いました」と伝えるだけでは、バージョンが異なると結果を再現できません。

そこで、「使用した薬剤（ライブラリ）の正確なリストと用量（バージョン）」を記述した「処方箋」が必要になります。これが requirements.txt ファイルです。

1. 「処方箋（requirements.txt）」の作成

仮想環境を有効化（Activate）した状態で、以下のコマンドを実行します。

# (.venv) が表示されていることを確認

# pip freeze の実行結果を requirements.txt ファイルに書き出す
pip freeze > requirements.txt

• pip freeze は、現在インストールされているライブラリと固定されたバージョンを一覧表示するコマンドです (Python Software Foundation 2025b)。
• > は「リダイレクト」と呼ばれ、コマンドの実行結果を requirements.txt という名前のファイルに書き出す操作です。

実行すると、プロジェクトフォルダ内に requirements.txt が作成されます。中身は以下のようになっています（バージョンは実行時点のものです）。

▼ requirements.txt の中身（例）

numpy==1.26.4
pandas==2.2.2
python-dateutil==2.9.0.post0
scikit-learn==1.5.0
# ... (その他、依存ライブラリ)

2. 「処方箋」からの環境再構築

共同研究者があなたのプロジェクト（requirements.txt を含む）を受け取った場合、彼（彼女）は以下の手順であなたと全く同じ「清潔野」を再現できます (Python Packaging Authority 2025)。

# (共同研究者のPCでの操作)

# 1. あなたのプロジェクトフォルダに移動
cd clinical_ai_project

# 2. 新しい仮想環境を作成
python -m venv .venv

# 3. 仮想環境を有効化
source .venv/bin/activate  # (OSに応じてコマンドを選択)

# 4. 「処方箋」を基に必要なライブラリを一括インストール
pip install -r requirements.txt

この pip install -r コマンドが、医療AI研究における「再現性の担保」の第一歩となります。

---

開発のベストプラクティス：VS CodeとGit連携

C30.xシリーズで学ぶツール群は、このvenvの運用を前提として連携します。

1. VS Codeとの連携

VS Codeは非常に賢く、プロジェクトフォルダ内に .venv フォルダを見つけると、自動的にそれをPythonの実行環境（インタプリタ）として認識します。

• VS Codeを開くと、右下または左下にPythonのバージョンが表示されます。ここが (.venv) を指していることを確認してください。
• もし認識されていない場合も、ステータスバーのPythonバージョン表示をクリックし、リストから .venv 内のPythonインタプリタを選択するだけで、VS Code全体（ターミナル、デバッガ、Jupyter機能）が「清潔野」モードに切り替わります。

2. Gitとの連携（.gitignore）

requirements.txt（処方箋）はGitで共有すべきですが、.venv フォルダ（薬剤トレイそのもの）は絶対にGitで共有してはいけません。

• 理由: .venv フォルダはOSに依存し、サイズが非常に大きくなるためです。処方箋さえあれば、トレイは各自で（pip install -rで）用意できます。

プロジェクトのルート（requirements.txt と同じ場所）に .gitignore という名前のファイルを作成し、以下のように記述します。

▼ .gitignore

# 仮想環境フォルダ（OS問わず）
.venv/
venv/
*.env

# Pythonが自動生成するキャッシュファイル
__pycache__/
*.pyc

これにより、Gitは .venv フォルダを意図的に無視するようになり、安全なバージョン管理が可能になります。

---

まとめと次のステップ

今回は、医療AI開発の基盤となる「仮想環境 venv」について、医療現場の「清潔野」のアナロジーを用いて学びました。

• venvは、プロジェクトごとの隔離された「清潔野」である。
• pip install で必要な器具（ライブラリ）を揃える。
• pip freeze > requirements.txt で「処方箋」を作成する。
• pip install -r requirements.txt で「処方箋」から環境を再現する。
• .venv フォルダ自体は .gitignore で管理対象外とする。

この venv は、Python標準で軽量かつ強力なツールですが、万能ではありません。例えば、深層学習で必須となるGPUドライバ（CUDA）のような、Pythonの「外側」にある複雑な依存関係は管理できません。

次回（C30.5）は、こうしたPython以外のライブラリも管理できる、より強力な環境管理ツール「conda」や、開発環境と本番環境をOSごと「滅菌パック」化する究極の技術「Docker」について学んでいきます。

※本記事は情報提供を目的としたものであり、特定の治療法を推奨するものではありません。健康に関するご懸念やご相談は、必ず専門の医療機関にご相談ください。

---

参考文献

• Python Packaging Authority. (2025). Requirements Files. Python Packaging User Guide. (Accessed 2025-11-17).
• Python Software Foundation. (2025a). venv — Creation of virtual environments. Python 3.12.4 documentation. (Accessed 2025-11-17).
• Python Software Foundation. (2025b). pip documentation v24.0. (Accessed 2025-11-17).
• Stodden, V., Miguez, S. & McNutt, M. (2018). Changing expectations for computational research: Reproducibility and replicability. Proceedings of the National Academy of Sciences, 115(11), 2580-2581.
• Wilson, G., Aruliah, D. A., Brown, C. T., Chue Hong, N. P., Davis, M., Guy, R. T., Hinsen, K., James, A., Jarvis, S., Johnston, I., Linge, S., Plumbley, M. D. & Waugh, B. (2014). Good enough practices in scientific computing. PLoS computational biology, 10(6), e1003546.

---

ご利用規約（免責事項）

当サイト（以下「本サイト」といいます）をご利用になる前に、本ご利用規約（以下「本規約」といいます）をよくお読みください。本サイトを利用された時点で、利用者は本規約の全ての条項に同意したものとみなします。

第1条（目的と情報の性質）

1. 本サイトは、医療分野におけるAI技術に関する一般的な情報提供および技術的な学習機会の提供を唯一の目的とします。
2. 本サイトで提供されるすべてのコンテンツ（文章、図表、コード、データセットの紹介等を含みますが、これらに限定されません）は、一般的な学習参考用であり、いかなる場合も医学的な助言、診断、治療、またはこれらに準ずる行為（以下「医行為等」といいます）を提供するものではありません。
3. 本サイトのコンテンツは、特定の製品、技術、または治療法の有効性、安全性を保証、推奨、または広告・販売促進するものではありません。紹介する技術には研究開発段階のものが含まれており、その臨床応用には、さらなる研究と国内外の規制当局による正式な承認が別途必要です。
4. 本サイトは、情報提供を目的としたものであり、特定の治療法を推奨するものではありません。健康に関するご懸念やご相談は、必ず専門の医療機関にご相談ください。

第2条（法令等の遵守）
利用者は、本サイトの利用にあたり、医師法、医薬品、医療機器等の品質、有効性及び安全性の確保等に関する法律（薬機法）、個人情報の保護に関する法律、医療法、医療広告ガイドライン、その他関連する国内外の全ての法令、条例、規則、および各省庁・学会等が定める最新のガイドライン等を、自らの責任において遵守するものとします。これらの適用判断についても、利用者が自ら関係各所に確認するものとし、本サイトは一切の責任を負いません。

第3条（医療行為における責任）

1. 本サイトで紹介するAI技術・手法は、あくまで研究段階の技術的解説であり、実際の臨床現場での診断・治療を代替、補助、または推奨するものでは一切ありません。
2. 医行為等に関する最終的な判断、決定、およびそれに伴う一切の責任は、必ず法律上その資格を認められた医療専門家（医師、歯科医師等）が負うものとします。AIによる出力を、資格を有する専門家による独立した検証および判断を経ずに利用することを固く禁じます。
3. 本サイトの情報に基づくいかなる行為によって利用者または第三者に損害が生じた場合も、本サイト運営者は一切の責任を負いません。実際の臨床判断に際しては、必ず担当の医療専門家にご相談ください。本サイトの利用によって、利用者と本サイト運営者の間に、医師と患者の関係、またはその他いかなる専門的な関係も成立するものではありません。

第4条（情報の正確性・完全性・有用性）

1. 本サイトは、掲載する情報（数値、事例、ソースコード、ライブラリのバージョン等）の正確性、完全性、網羅性、有用性、特定目的への適合性、その他一切の事項について、何ら保証するものではありません。
2. 掲載情報は執筆時点のものであり、予告なく変更または削除されることがあります。また、技術の進展、ライブラリの更新等により、情報は古くなる可能性があります。利用者は、必ず自身で公式ドキュメント等の最新情報を確認し、自らの責任で情報を利用するものとします。

第5条（AI生成コンテンツに関する注意事項）
本サイトのコンテンツには、AIによる提案を基に作成された部分が含まれる場合がありますが、公開にあたっては人間による監修・編集を経ています。利用者が生成AI等を用いる際は、ハルシネーション（事実に基づかない情報の生成）やバイアスのリスクが内在することを十分に理解し、その出力を鵜呑みにすることなく、必ず専門家による検証を行うものとします。

第6条（知的財産権）

1. 本サイトを構成するすべてのコンテンツに関する著作権、商標権、その他一切の知的財産権は、本サイト運営者または正当な権利を有する第三者に帰属します。
2. 本サイトのコンテンツを引用、転載、複製、改変、その他の二次利用を行う場合は、著作権法その他関連法規を遵守し、必ず出典を明記するとともに、権利者の許諾を得るなど、適切な手続きを自らの責任で行うものとします。

第7条（プライバシー・倫理）
本サイトで紹介または言及されるデータセット等を利用する場合、利用者は当該データセットに付随するライセンス条件および研究倫理指針を厳格に遵守し、個人情報の匿名化や同意取得の確認など、適用される法規制に基づき必要とされるすべての措置を、自らの責任において講じるものとします。

第8条（利用環境）
本サイトで紹介するソースコードやライブラリは、執筆時点で特定のバージョンおよび実行環境（OS、ハードウェア、依存パッケージ等）を前提としています。利用者の環境における動作を保証するものではなく、互換性の問題等に起因するいかなる不利益・損害についても、本サイト運営者は責任を負いません。

第9条（免責事項）

1. 本サイト運営者は、利用者が本サイトを利用したこと、または利用できなかったことによって生じる一切の損害（直接損害、間接損害、付随的損害、特別損害、懲罰的損害、逸失利益、データの消失、プログラムの毀損等を含みますが、これらに限定されません）について、その原因の如何を問わず、一切の法的責任を負わないものとします。
2. 本サイトの利用は、学習および研究目的に限定されるものとし、それ以外の目的での利用はご遠慮ください。
3. 本サイトの利用に関連して、利用者と第三者との間で紛争が生じた場合、利用者は自らの費用と責任においてこれを解決するものとし、本サイト運営者に一切の迷惑または損害を与えないものとします。
4. 本サイト運営者は、いつでも予告なく本サイトの運営を中断、中止、または内容を変更できるものとし、これによって利用者に生じたいかなる損害についても責任を負いません。

第10条（規約の変更）
本サイト運営者は、必要と判断した場合、利用者の承諾を得ることなく、いつでも本規約を変更することができます。変更後の規約は、本サイト上に掲載された時点で効力を生じるものとし、利用者は変更後の規約に拘束されるものとします。

第11条（準拠法および合意管轄）
本規約の解釈にあたっては、日本法を準拠法とします。本サイトの利用および本規約に関連して生じる一切の紛争については、東京地方裁判所を第一審の専属的合意管轄裁判所とします。

---

For J³, may joy follow you.