venvとrequirements.txtでいつでも動くPython環境を作る | SkillhubAI(スキルハブエーアイ)

venvとrequirements.txtでいつでも動くPython環境を作る

「昨日まで動いていたコードが動かない!」の正体

プログラミングを始めて少し経つと、必ずこんな経験をします。昨日まで完璧に動いていたコードが、今日突然動かなくなる。何も変更していないのに、なぜかエラーが出る。そんな時、「自分が何か間違ったのかな?」と不安になりますよね。

でも安心してください。これは技術的な問題で、あなたのせいではありません。そして、きちんとした解決策があります。

こんなStreamlitアプリを作ったとします:

# app.py
import streamlit as st
import pandas as pd

st.title("データ分析アプリ")
df = pd.read_csv("data.csv")
st.dataframe(df, use_container_width=True)  # ← ここが問題の箇所

昨日(2024年8月):完璧に動作 ✅
今日(2025年1月):突然エラー! ❌

❌ エラーメッセージ
AttributeError: 'DataFrame' object has no attribute 'use_container_width'

何が起こったのでしょうか?

実は、あなたのPCで自動的にライブラリがアップデートされて、Streamlit 1.28 から 1.48 に更新されたんです。新しいバージョンではuse_container_widthパラメータの使い方が変わったため、古いコードが動かなくなりました。

これはあなたが悪いわけではありません。ライブラリの開発者が仕様を変更したからです。

同じことがこんなコードでも起こります:

# 数ヶ月前に書いたコード
import pandas as pd
df = pd.DataFrame({"名前": ["田中", "佐藤", "鈴木"]})
new_row = {"名前": "高橋"}
df = df.append(new_row, ignore_index=True)  # ← この書き方が古くなった

⚠️ 警告メッセージ
FutureWarning: The frame.append method is deprecated and will be removed from pandas in a future version.
「deprecated って何?使えなくなるの?」

これもよくあるパターンです。pandas 2.0でappendメソッドが廃止され、pd.concatを使うように変更されました。

解決策:venvとrequirements.txtという強力な味方

簡単に言うと:

1. venv(仮想環境) = プロジェクトごとに独立したPython環境を作る
2. requirements.txt = 使用するライブラリのバージョンを記録しておく

この2つを使うことで、いつでも、どこでも、誰でも同じ環境を再現できるようになります。

想像してみてください。友達にプロジェクトを渡すとき、新しいパソコンで作業するとき、半年後に自分のコードを見返すとき。どんな状況でも、コマンド一つで完全に同じ環境が作れるんです。

# これだけで、あなたと全く同じ環境が作れる!
pip install -r requirements.txt

素晴らしいと思いませんか?

venv(仮想環境)って何?なぜ必要?

venvは「Virtual Environment(仮想環境)」の略で、プロジェクトごとに独立したPython環境を作るツールです。

問題:グローバル環境の落とし穴

通常、ライブラリをpip installすると、パソコン全体の共通領域(グローバル環境)にインストールされます。これが問題の原因なんです。

❌ グローバル環境の問題

すべてのプロジェクトが同じライブラリを共有するため:
• プロジェクトAは古いstreamlit 1.28が必要
• プロジェクトBは新しいstreamlit 1.48が必要
• 両方を同時にインストールできない!
• 新しいライブラリをインストールすると、古いプロジェクトが動かなくなる

これが「昨日まで動いていたコードが動かない」の正体です。決してあなたが悪いわけではないんです。

解決策:venvで環境を分離

venvを使うと、まるでプロジェクトごとに専用のパソコンを用意するような感覚で、独立した環境を作れます。

✅ venvで解決!

プロジェクトA: streamlit==1.28, pandas==1.5.3
プロジェクトB: streamlit==1.48, pandas==2.1.0

それぞれ独立して動作し、お互いに影響しません。

まるで、プロジェクトごとに専用の作業部屋を持っているような感じですね。

venvの使い方:ステップバイステップ

実際にvenvを使ってみましょう。最初は少し手順が多く感じるかもしれませんが、慣れてしまえば3分もかかりません。

ステップ1:新しいプロジェクトの準備


# プロジェクトフォルダを作成
mkdir my_ai_app
cd my_ai_app

ステップ2:仮想環境を作成


# 仮想環境を作成
python -m venv venv

実行すると、こんなフォルダ構造ができます:

my_ai_app/
└── venv/          # ← 仮想環境フォルダ(新しく作られた!)
    ├── bin/       # 実行ファイル(Mac/Linux)
    ├── Scripts/   # 実行ファイル(Windows)
    ├── lib/       # ライブラリ保存場所
    └── ...        # その他の設定ファイル

これで、あなた専用のPython環境ができました!でも、まだ使い始めていません。

ステップ3:仮想環境を有効化(重要!)


# Mac/Linux の場合
source venv/bin/activate

# Windows の場合
venv\Scripts\activate

✅ 成功のサイン
コマンドが成功すると、ターミナルの表示が変わります:

有効化前: $
有効化後: (venv) $ ← カッコ内に環境名が表示される

この (venv) が見えたら、仮想環境が有効になっています!

これで、専用の作業部屋に入った状態です。ここでインストールするライブラリは、この部屋の中だけで使われます。

ステップ4:必要なライブラリをインストール


# 仮想環境内でライブラリをインストール
(venv) $ pip install streamlit==1.48.0
(venv) $ pip install openai==1.57.0
(venv) $ pip install pandas==2.1.0

バージョンを指定することで、「確実にこのバージョンを使う」と明示できます。これが「いつでも動く」の秘訣です!

ステップ5:開発・実行

# app.py
import streamlit as st
import pandas as pd

st.title("私の素晴らしいアプリ 🚀")
st.write("venvで作った安全な環境で動いています!")

df = pd.DataFrame({
    "項目": ["Python", "Streamlit", "venv"],
    "習得度": [80, 70, 100]
})
st.dataframe(df)

# アプリを実行
(venv) $ streamlit run app.py

きっと完璧に動くはずです!そして、この環境は他のプロジェクトに影響されることなく、永続的に安定しています。

ステップ6:作業終了時

# 仮想環境を無効化
(venv) $ deactivate

# 通常の状態に戻る
$

requirements.txtで環境をシェア

venvで安定した環境を作れました。でも、「この環境を他の人に教えたい」「新しいパソコンでも同じ環境を作りたい」という時はどうすればいいでしょうか?

そこで登場するのがrequirements.txtです。

requirements.txtって何?

requirements.txtは、現在の環境にインストールされているライブラリとバージョンを記録したファイルです。

requirements.txtの作成方法

自動生成(おすすめ)

# 仮想環境を有効化してから
(venv) $ pip freeze > requirements.txt

これで、こんなファイルが作られます:

# requirements.txt(自動生成された内容)
streamlit==1.48.0
openai==1.57.0
pandas==2.1.0
numpy==1.24.0
altair==4.2.2
click==8.1.3
protobuf==4.23.4
# ... その他の依存関係

手動作成(最小限)

# requirements.txt(手動作成)
streamlit==1.48.0
openai==1.57.0
pandas==2.1.0

requirements.txtから環境を復元

ここからが本当にすごいところです。requirements.txtがあれば、コマンド一つで全く同じ環境を作れます

# 友達のパソコンで
# 1. プロジェクトをダウンロード
git clone https://github.com/yourname/awesome-project.git
cd awesome-project

# 2. 仮想環境作成・有効化
python -m venv venv
source venv/bin/activate

# 3. requirements.txtから一括インストール
(venv) $ pip install -r requirements.txt

# 4. 完了!すぐに実行可能
(venv) $ streamlit run app.py

あなたのパソコンで動いていたアプリが、友達のパソコンでも一発で動く!これが、プロが使っている技術です。

実際の開発フロー:日常的な使い方

新規プロジェクト作成の流れ

# 1. プロジェクト準備
mkdir chat_app
cd chat_app

# 2. 仮想環境作成・有効化
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 3. 基本的なライブラリをインストール
(venv) $ pip install streamlit==1.48.0
(venv) $ pip install openai==1.57.0

# 4. requirements.txt作成
(venv) $ pip freeze > requirements.txt

# 5. コードを作成
(venv) $ nano main.py

毎日の開発作業

# 1. プロジェクトフォルダに移動
cd my_project

# 2. 仮想環境有効化(重要!)
source venv/bin/activate

# 3. 開発作業
(venv) $ streamlit run app.py

# 4. 新しいライブラリが必要になった場合
(venv) $ pip install requests==2.31.0
(venv) $ pip freeze > requirements.txt  # 忘れずに更新!

# 5. 作業終了
(venv) $ deactivate

💡 習慣にしよう
• プロジェクトフォルダに入ったら、まず source venv/bin/activate
• 新しいライブラリを入れたら、pip freeze > requirements.txt
• 作業終了前に deactivate

この3つが習慣になれば、もうトラブルとは無縁です!

既存プロジェクトを他のPCで実行

# 1. プロジェクトをダウンロード
git clone https://github.com/awesome-user/cool-project.git
cd cool-project

# 2. 仮想環境作成・有効化
python -m venv venv
source venv/bin/activate

# 3. requirements.txtから環境復元
(venv) $ pip install -r requirements.txt

# 4. 即座に実行可能!
(venv) $ streamlit run app.py

よくあるエラーと解決法:困った時のガイド

エラー1:「ModuleNotFoundError: No module named 'streamlit'」

❌ エラーメッセージ
ModuleNotFoundError: No module named 'streamlit'
🤔 こんな時に起こる:
「streamlitインストールしたはずなのに...」

原因: 仮想環境が有効化されていない

解決策:

# 仮想環境を有効化してから実行
source venv/bin/activate
(venv) $ streamlit run app.py

ターミナルに (venv) が表示されているか確認しましょう。これが見えていれば、仮想環境が有効になっています。

エラー2:「AttributeError: 'DataFrame' object has no attribute 'append'」

❌ エラーメッセージ
AttributeError: 'DataFrame' object has no attribute 'append'
🤔 こんな時に起こる:
「昨日まで動いていたpandasのコードが...」

原因: pandasのバージョンが2.0以上で、appendメソッドが廃止された

解決策:

# 方法1:古いバージョンに固定
echo "pandas==1.5.3" >> requirements.txt
pip install -r requirements.txt

# 方法2:新しい書き方に変更
# 古い書き方:df.append(new_row, ignore_index=True)
# 新しい書き方:pd.concat([df, pd.DataFrame([new_row])], ignore_index=True)

エラー3:「'venv' is not recognized」(Windows)

❌ エラーメッセージ
'venv' is not recognized as an internal or external command
🤔 こんな時に起こる:
「WindowsでPythonを使い始めたばかり」

解決策:

# Python経由でvenvを実行
python -m venv venv

# PowerShellで有効化
venv\Scripts\Activate.ps1

# 権限エラーが出る場合
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

エラー4:「pip: command not found」

❌ エラーメッセージ
pip: command not found
🤔 こんな時に起こる:
「Pythonはインストールしたはずなのに...」

解決策:

# python -m pip を使用
python -m pip install streamlit

# または、python3で試す
python3 -m pip install streamlit

エラーが出ても焦らないでください。エラーメッセージをよく読んで、上記の解決策を試してみてください。それでも解決しない場合は、エラーメッセージをそのままGoogle検索すると、多くの場合解決策が見つかります。

プロジェクト構成のベストプラクティス

きちんとしたプロジェクト構成を知っておくと、後々の管理がとても楽になります。

推奨フォルダ構造

my_ai_project/
├── venv/                 # 仮想環境(.gitignoreに追加)
├── requirements.txt      # ライブラリ一覧
├── .gitignore           # Git除外設定
├── README.md            # プロジェクト説明
├── main.py              # メインコード
├── utils/               # ユーティリティ関数
│   └── helpers.py
├── data/                # データファイル
│   └── sample.csv
└── tests/               # テストファイル(将来的に)
    └── test_main.py

.gitignoreの設定

Gitを使う場合、以下のファイルは共有しないようにします:

# .gitignore
venv/          # 仮想環境は共有しない
__pycache__/   # Pythonキャッシュ
*.pyc          # コンパイル済みファイル
.env           # 環境変数ファイル(APIキーなど)
.DS_Store      # macOSファイル
*.log          # ログファイル
.vscode/       # エディタ設定(個人設定)

重要: venv/フォルダはGitで共有しません。代わりにrequirements.txtで環境を共有します。これにより、リポジトリのサイズを小さく保てます。

README.mdの例

# My AI App

StreamlitとOpenAIを使った素晴らしいAIアプリです。

## セットアップ


```bash
# 仮想環境作成・有効化
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# ライブラリインストール
pip install -r requirements.txt

# 実行
streamlit run main.py

必要な環境

  • Python 3.12以上
  • OpenAI APIキー

このように、**誰でも簡単に始められる**説明を書いておくと、チーム開発や将来の自分にとって非常に有用です。

## **チーム開発での運用:みんなで使う時のコツ**

### **環境の統一**


```bash
# チーム全員で同じPythonバージョンを使用
python --version  # Python 3.12.0

# .python-versionファイルで明示
echo "3.12.0" > .python-version

開発用と本番用の分離

# requirements-dev.txt(開発用)
streamlit==1.48.0
openai==1.57.0
pytest==7.4.0     # テスト用
black==23.7.0      # コード整形
flake8==6.0.0      # リンター

# requirements.txt(本番用)
streamlit==1.48.0
openai==1.57.0

# 開発環境セットアップ
pip install -r requirements-dev.txt

# 本番環境デプロイ
pip install -r requirements.txt

実際のトラブル解決例:よくある具体的なケース

ケース1:Streamlitアプリが古い書き方で動かない

🚨 問題発生
数ヶ月前に作ったStreamlitアプリが動かなくなった

エラー:
AttributeError: module 'streamlit' has no attribute 'beta_columns'

原因: Streamlit 1.0でst.beta_columnsst.columnsに変更された

解決策:

# 方法1:古いバージョンに固定
echo "streamlit==0.89.0" > requirements.txt
pip install -r requirements.txt

# 方法2:コードを新しい書き方に変更
# 古い:st.beta_columns(2)
# 新しい:st.columns(2)

✅ 学んだこと
venvとrequirements.txtを使っていれば、このような問題は起きません。最初からバージョンを固定していれば、アプリは永続的に動き続けます。

ケース2:友達のPCでアプリが動かない

🚨 問題発生
自分のPCでは完璧に動くアプリを友達に送ったら「動かない」と言われた

友達のエラー:
ModuleNotFoundError: No module named 'langchain'

原因: 友達のPCにはlangchainがインストールされていない

解決策:

# あなたがやること
pip freeze > requirements.txt
git add requirements.txt
git commit -m "Add requirements.txt"

# 友達がやること
git clone your-project
cd your-project
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
streamlit run app.py  # 完璧に動く!

ケース3:パッケージの依存関係でエラー

🚨 問題発生
新しいライブラリをインストールしたら、既存のコードが動かなくなった

エラー:
ImportError: cannot import name 'soft_unicode' from 'markupsafe'

原因: ライブラリ同士の依存関係で競合が発生

解決策:

# 仮想環境を作り直し
deactivate
rm -rf venv
python -m venv venv
source venv/bin/activate

# requirements.txtから復元
pip install -r requirements.txt

✅ venvの素晴らしさ
グローバル環境なら、この問題の解決は非常に困難です。でもvenvなら、環境を丸ごと作り直せるので、いつでもクリーンな状態に戻れます。

まとめ:確実に動くPython環境の作り方

長いレッスンでしたが、お疲れさまでした!最後に、重要なポイントをまとめましょう。

今日学んだ最重要ポイント: - venv:プロジェクトごとに独立した環境を作る - requirements.txt:ライブラリのバージョンを記録する - この2つで:いつでも、どこでも、誰でも同じ環境を再現できる

今日から実践する3つの習慣

⚠️ 初心者へのアドバイス
最初は == による完全一致がおすすめです。確実に動く環境を作ることが最優先です。慣れてきたら、他の指定方法も試してみてください。

1. 新プロジェクト

mkdir project && cd project
python -m venv venv
source venv/bin/activate

2. ライブラリ追加

pip install new-library
pip freeze > requirements.txt

3. 環境復元

python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

これで解決される問題

もう、こんな悩みとはお別れです:

  • ✅ 「昨日まで動いていたコードが動かない」
  • ✅ 「友達のPCで動かない」
  • ✅ 「新しいパソコンで環境構築が大変」
  • ✅ 「ライブラリが競合してエラーが出る」
  • ✅ 「半年前のプロジェクトが動かない」

あなたは今、プロの開発者が当たり前に使っている技術を習得しました。venvとrequirements.txtは、実際の開発現場で毎日使われている必須スキルです。

この技術を身につけたあなたは、もう安心してPython開発を進められます。新しいプロジェクトで実践してみて、既存のプロジェクトもvenv化してみましょう。友達とプロジェクトを共有して、その便利さを実感してください。

これだけ覚えれば、もう「動かない」で悩むことはありません!

今日から新しいプロジェクトでは必ずvenvとrequirements.txtを使って、プロフェッショナルなPython開発環境を構築しましょう。