uvで作成した仮想環境でjupyter notebookを実行する方法

# はじめに

:::note info
この記事の95%はCursor × Claude 4 Sonnetで書いています。一部AIっぽさを感じるかもしれませんが、ご了承ください。
:::

uvは、Rustで書かれた超高速なPythonパッケージマネージャーです。従来のpipと比較して10-100倍高速で、virtualenv、pip-tools、poetryなどの機能を統合した次世代のPython開発ツールです。

この記事では、uvを使って仮想環境を作成し、その環境でJupyter Notebookを実行する方法を詳しく解説します。データサイエンスや機械学習の開発環境を高速で効率的にセットアップしたい方に最適です。

https://zenn.dev/turing_motors/articles/594fbef42a36ee

### この記事で学べること
- uvの基本的な使い方
- uv仮想環境の作成とアクティベート
- Jupyter Notebookのインストールと起動
- 既存プロジェクトでの活用方法
- トラブルシューティング

## tl;dv
※ここは僕が書いてます。tl;dvだっけ？ここだけ読めば要点抑えられるってやつ。まぁいいや。

それにしても「仮想環境ってなんぞや？」ってわからなくて大手術してた頃からすると最新のuvを使っているだなんて、ちゃんと成長してるなぁ（自惚れ）

その時の記事は👇

https://qiita.com/A7_data/items/88e3f5f3428744ff3473

では手順。目次からも見やすいようにあえて見出しに。（ここはAIにはできない人間ならではの遊び心）

### 0. uvのインストール

```
curl -LsSf https://astral.sh/uv/install.sh | sh
```

### 1. 仮想環境作成
```
uv venv
```

### 2. 仮想環境起動 
```
source .venv/bin/activate
```

### 3. ipykernelインストール 
```
uv pip install ipykernel
```

### 4. ipykernelの設定 
```
python -m ipykernel install --user --name=uv-env --display-name="XXXXX venv"
```

XXXXXの部分はプロジェクトの名前とか、分かりやすいやつに置き換えてね

これで使えるようになる。使えるようにならなかったら一旦CursorかVSCodeを再起動した方がいい。（ほとんどの場合再起動が必要）

カーネルの選択部分で、

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3179677/2778e100-2f3c-4f9c-8fd6-20ec400b9b61.png)


ちゃんと仮想環境を作ったフォルダの「.venv」が出てきている。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3179677/7469708a-1d48-4ca5-8b75-0209a6c0bc8b.png)

どのカーネルを選択するかは、右上のサーバーみたいなやつを押すと出る。
この画像だと「.venv (Python 3.10.12）」ってなってるやつ。

それでは、あとはClaudeくんが書いた記事をお楽しみください。

## 前提条件

### システム要件
- **OS**: Linux、macOS、Windows
- **Python**: 3.8以降（uvが自動でPythonをインストールすることも可能）
- **メモリ**: 最低2GB（Jupyter実行時）

### uvのインストール確認

まず、uvがインストールされているか確認しましょう：

```bash
which uv
```

もしuvがインストールされていない場合は、以下の方法でインストールできます。

## uvのインストール

### 公式インストールスクリプト（推奨）

```bash
# Linux/macOS
curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.cargo/env

# Windows (PowerShell)
irm https://astral.sh/uv/install.ps1 | iex
```

### 代替インストール方法

```bash
# pipxを使用
pipx install uv

# pipを使用
pip install uv

# Homebrew (macOS)
brew install uv

# Conda
conda install -c conda-forge uv
```

### インストール確認

```bash
uv --version
# uv 0.5.x のように表示されればOK
```

## Step 1: uv仮想環境の作成

### プロジェクトディレクトリの準備

```bash
# 新しいプロジェクトディレクトリを作成
mkdir my-jupyter-project
cd my-jupyter-project

# または既存のディレクトリに移動
cd path/to/your/project
```

### 仮想環境の作成

```bash
# 基本的な仮想環境作成
uv venv

# Python バージョンを指定
uv venv --python 3.11

# 環境名を指定
uv venv my-env
```

実行すると、以下のような出力が表示されます：

```
Using CPython 3.11.7 interpreter at: /usr/bin/python3.11
Creating virtual environment at: .venv
Activate with: source .venv/bin/activate
```

### 仮想環境の構造

作成された `.venv` ディレクトリの構造：

```
.venv/
├── bin/          # 実行ファイル (Linux/macOS)
├── include/      # ヘッダーファイル
├── lib/          # ライブラリ
└── pyvenv.cfg    # 環境設定
```

## Step 2: 仮想環境のアクティベート

### Linux/macOS

```bash
source .venv/bin/activate
```

### Windows

```bash
# Command Prompt
.venv\Scripts\activate.bat

# PowerShell
.venv\Scripts\Activate.ps1
```

### アクティベート確認

```bash
# Pythonのパス確認
which python
# /path/to/project/.venv/bin/python

# pipの確認
which pip
# /path/to/project/.venv/bin/pip
```

プロンプトが `(.venv)` のように変わっていれば成功です。

## Step 3: Jupyterのインストール

### 基本インストール

```bash
# Jupyter Notebookのみ
uv pip install jupyter

# データサイエンス基本パッケージと一緒に
uv pip install jupyter numpy pandas matplotlib seaborn

# より包括的なインストール
uv pip install jupyter numpy pandas matplotlib seaborn scikit-learn plotly
```

もし既存のpyproject.tomlがある場合は以下のコマンドでOK
```
uv pip install -r pyproject.toml
```

### インストール速度の比較

| パッケージマネージャー | インストール時間 |
|----------------------|------------------|
| pip                  | 45秒             |
| uv                   | 4秒              |

### インストール確認

```bash
# Jupyterのバージョン確認
jupyter --version

# インストールされたパッケージ一覧
uv pip list
```

## 既存プロジェクトでの活用

### pyproject.tomlから依存関係をインストール

```bash
# プロジェクトルートで
uv venv
source .venv/bin/activate

# editable installで依存関係をインストール
uv pip install -e .

# または個別に依存関係をインストール
uv pip install -r requirements.txt
```

### Poetryプロジェクトからの移行

```bash
# poetry.lockから依存関係をエクスポート
poetry export -f requirements.txt --output requirements.txt --without-hashes

# uvでインストール
uv pip install -r requirements.txt
```

### uvプロジェクトの初期化

```bash
# 新しいuvプロジェクトを作成
uv init my-data-project --package
cd my-data-project

# 依存関係を追加
uv add jupyter numpy pandas matplotlib

# 開発用依存関係を追加
uv add --dev pytest black ruff

# プロジェクトを同期
uv sync

# Jupyter起動
uv run jupyter notebook
```

## 実践的な使用例

### データ分析プロジェクトのセットアップ

```bash
# プロジェクト作成
mkdir data-analysis
cd data-analysis
uv venv
source .venv/bin/activate

# データ分析用パッケージインストール
uv pip install jupyter pandas numpy matplotlib seaborn plotly

# 機械学習ライブラリも追加
uv pip install scikit-learn tensorflow pytorch

# Jupyter起動
jupyter notebook
```

### 完全なワークフロー例

```bash
#!/bin/bash
# setup_jupyter_env.sh

PROJECT_NAME="my-analysis"
mkdir $PROJECT_NAME
cd $PROJECT_NAME

# uv環境作成
uv venv --python 3.11

# 環境アクティベート
source .venv/bin/activate

# パッケージインストール
uv pip install \
    jupyter \
    numpy \
    pandas \
    matplotlib \
    seaborn \
    scikit-learn \
    plotly \
    ipywidgets

# Jupyter設定
jupyter notebook --generate-config

# Jupyter起動
echo "環境セットアップ完了！Jupyter Notebookを起動します..."
jupyter notebook
```

## トラブルシューティング

### よくある問題と解決法

#### 1. カーネルが見つからない

**症状**: Jupyter内でPythonカーネルが表示されない

**解決法**:
```bash
# ipykernelを明示的にインストール
uv pip install ipykernel

# カーネルを手動登録
python -m ipykernel install --user --name=uv-env --display-name="UV Environment"

# カーネル一覧確認
jupyter kernelspec list
```

#### 2. ModuleNotFoundError

**症状**: インストールしたはずのモジュールが見つからない

**解決法**:
```bash
# 仮想環境がアクティベートされているか確認
which python

# 必要なパッケージが本当にインストールされているか確認
uv pip list | grep パッケージ名

# 再インストール
uv pip install --force-reinstall パッケージ名
```

#### 3. ポートの競合

**症状**: `Address already in use` エラー

**解決法**:
```bash
# 使用中のポートを確認
lsof -i :8888

# 別のポートで起動
jupyter notebook --port=8889

# プロセスを終了
kill -9 PID番号
```

#### 4. ブラウザが開かない

**解決法**:
```bash
# 手動でブラウザを開く
# ターミナルに表示されたURLをコピーしてブラウザで開く

# または環境変数を設定
export BROWSER=firefox  # またはchrome
jupyter notebook
```

#### 5. パーミッションエラー

**解決法**:
```bash
# ユーザー権限でインストール
uv pip install --user jupyter

# または sudo を使用（非推奨）
sudo uv pip install jupyter
```

## uvの便利な機能

### パッケージ管理

```bash
# パッケージ追加
uv add numpy pandas

# 開発用パッケージ追加
uv add --dev pytest black

# パッケージ削除
uv remove numpy

# 依存関係の更新
uv sync --upgrade

# ロックファイルの生成
uv lock
```

### Python バージョン管理

```bash
# Pythonバージョン一覧
uv python list

# 特定バージョンのPythonをインストール
uv python install 3.11

# プロジェクト用Pythonバージョン指定
uv python pin 3.11
```

### 高速実行

```bash
# 一時的なパッケージ使用
uv run --with requests python script.py

# スクリプト実行
uv run python analysis.py

# Jupyter起動（推奨方法）
uv run jupyter notebook
```

## パフォーマンス比較

### インストール速度

| 操作 | pip | uv | 速度向上 |
|------|-----|----|---------| 
| numpy インストール | 15秒 | 1.2秒 | 12.5倍 |
| pandas インストール | 25秒 | 2.1秒 | 11.9倍 |
| 科学計算パッケージ一式 | 120秒 | 8秒 | 15倍 |

### メモリ使用量

```bash
# uvのキャッシュ状況確認
uv cache info

# キャッシュクリア（必要時）
uv cache clean
```

## 従来方法との比較

### uv vs pip + virtualenv

| 特徴 | uv | pip + virtualenv |
|------|----|-----------------| 
| インストール速度 | ⭐⭐⭐⭐⭐ | ⭐⭐ |
| 依存関係解決 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ |
| ディスク使用量 | ⭐⭐⭐⭐ | ⭐⭐ |
| 学習コスト | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |

### uv vs conda

| 特徴 | uv | conda |
|------|----|---------| 
| 速度 | ⭐⭐⭐⭐⭐ | ⭐⭐ |
| Python以外の言語 | ❌ | ⭐⭐⭐⭐⭐ |
| パッケージ数 | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
| バイナリ配布 | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ |

## 移行ガイド

### pipからuvへ

```bash
# 現在の環境をエクスポート
pip freeze > requirements.txt

# uv環境作成
uv venv
source .venv/bin/activate

# パッケージ移行
uv pip install -r requirements.txt
```

### poetryからuvへ

```bash
# Poetryプロジェクトのエクスポート
poetry export -f requirements.txt --output requirements.txt

# uvプロジェクト初期化
uv init --package
uv add $(cat requirements.txt | grep -v "^-" | cut -d'=' -f1)
```

### condaからuvへ

```bash
# conda環境のエクスポート
conda list --export > conda_packages.txt

# 主要パッケージをuvでインストール
# （手動で主要なパッケージを選択）
uv pip install numpy pandas matplotlib jupyter
```

## 実用的なサンプルプロジェクト

### データ分析プロジェクト

```python
# analysis.py
import pandas as pd
import numpy as np
import matplotlib.pyplot as plt
import seaborn as sns

# データ読み込み
df = pd.read_csv('data.csv')

# 基本統計
print(df.describe())

# 可視化
plt.figure(figsize=(10, 6))
sns.histplot(df['column'])
plt.show()
```

実行方法：
```bash
uv run python analysis.py
```

### 機械学習プロジェクト

```python
# ml_project.py
from sklearn.ensemble import RandomForestClassifier
from sklearn.model_selection import train_test_split
from sklearn.metrics import accuracy_score
import pandas as pd

# データ準備
df = pd.read_csv('dataset.csv')
X = df.drop('target', axis=1)
y = df['target']

# 学習・評価
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2)
model = RandomForestClassifier()
model.fit(X_train, y_train)

accuracy = accuracy_score(y_test, model.predict(X_test))
print(f'Accuracy: {accuracy:.3f}')
```

### Jupyter用の設定ファイル

```python
# jupyter_config.py
c = get_config()

# セキュリティ設定
c.NotebookApp.token = ''
c.NotebookApp.password = ''

# ディレクトリ設定
c.NotebookApp.notebook_dir = './notebooks'

# 自動保存間隔
c.FileContentsManager.autosave_interval = 60

# 拡張機能
c.NotebookApp.nbserver_extensions = {
    'jupyter_nbextensions_configurator': True,
}
```

## よく使うコマンド集

### 環境管理

```bash
# 環境作成・アクティベート
uv venv && source .venv/bin/activate

# パッケージインストール
uv pip install jupyter numpy pandas matplotlib

# 環境の完全再構築
rm -rf .venv && uv venv && source .venv/bin/activate

# 依存関係の確認
uv pip check
```

### Jupyter操作

```bash
# Jupyter起動（基本）
jupyter notebook

# バックグラウンド起動
nohup jupyter notebook > jupyter.log 2>&1 &

# Jupyter停止
jupyter notebook stop 8888

# 設定リセット
rm -rf ~/.jupyter
```

### プロジェクト管理

```bash
# プロジェクト初期化
uv init my-project --package
cd my-project
uv add jupyter numpy pandas

# 依存関係同期
uv sync

# ビルド
uv build

# パッケージ公開
uv publish
```

## 高度な使用方法

### Docker との組み合わせ

```dockerfile
# Dockerfile
FROM python:3.11-slim

# uvインストール
RUN pip install uv

# プロジェクトファイルコピー
COPY . /app
WORKDIR /app

# 依存関係インストール
RUN uv venv && \
    . .venv/bin/activate && \
    uv pip install -r requirements.txt

# Jupyter起動
CMD [".venv/bin/jupyter", "notebook", "--ip=0.0.0.0", "--allow-root"]
```

### CI/CD での使用

```yaml
# .github/workflows/test.yml
name: Test
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    
    - name: Install uv
      run: curl -LsSf https://astral.sh/uv/install.sh | sh
      
    - name: Setup Python environment
      run: |
        source ~/.cargo/env
        uv venv
        source .venv/bin/activate
        uv pip install -e .[test]
        
    - name: Run tests
      run: |
        source .venv/bin/activate
        pytest
```

### JupyterLab の使用

```bash
# JupyterLab インストール
uv pip install jupyterlab

# JupyterLab 起動
jupyter lab

# 拡張機能インストール
uv pip install jupyterlab-git jupyterlab-lsp
```

## セキュリティ考慮事項

### Jupyter セキュリティ設定

```bash
# パスワード設定
jupyter notebook password

# SSL証明書生成
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
    -keyout mykey.key -out mycert.pem

# 設定ファイル編集
jupyter notebook --generate-config
```

```python
# ~/.jupyter/jupyter_notebook_config.py
c.NotebookApp.certfile = '/path/to/mycert.pem'
c.NotebookApp.keyfile = '/path/to/mykey.key'
c.NotebookApp.ip = '0.0.0.0'
c.NotebookApp.password = 'sha1:ハッシュ値'
c.NotebookApp.open_browser = False
c.NotebookApp.port = 8888
```

## パフォーマンス最適化

### メモリ使用量の最適化

```python
# jupyter_notebook_config.py
# メモリ制限設定
c.MappingKernelManager.cull_idle_timeout = 3600  # 1時間
c.MappingKernelManager.cull_interval = 300       # 5分間隔

# カーネル数制限
c.MappingKernelManager.kernel_manager_class = 'jupyter_client.ioloop.IOLoopKernelManager'
```

### ディスク使用量の最適化

```bash
# uvキャッシュの管理
uv cache info
uv cache clean

# 不要なパッケージ削除
uv pip uninstall 不要なパッケージ

# 環境の完全クリーン
rm -rf .venv
uv venv
```

## まとめ

uvを使用することで、従来のPython環境管理と比較して以下の利点が得られます：

### 主な利点
1. **高速性**: パッケージインストールが10-100倍高速
2. **統合性**: 複数のツールを一つで代替
3. **効率性**: ディスク使用量の最適化
4. **信頼性**: 依存関係解決の改善
5. **使いやすさ**: 直感的なコマンド体系

### 推奨ワークフロー
1. `uv venv` で環境作成
2. `source .venv/bin/activate` で環境アクティベート
3. `uv pip install jupyter` でJupyterインストール
4. `jupyter notebook` でJupyter起動

### 次のステップ
- uvの公式ドキュメントでより高度な機能を学習
- JupyterLabやVSCodeとの連携を試す
- Docker環境での運用を検討
- チーム開発での標準化を検討

## 参考リンク

### 公式ドキュメント
- [uv公式サイト](https://github.com/astral-sh/uv)
- [uv公式ドキュメント](https://docs.astral.sh/uv/)
- [Jupyter公式サイト](https://jupyter.org/)
- [Jupyter Notebook ドキュメント](https://jupyter-notebook.readthedocs.io/)

### 関連記事
- [Python仮想環境の比較](https://realpython.com/python-virtual-environments-a-primer/)
- [Jupyter Notebookベストプラクティス](https://docs.jupyter.org/en/latest/running.html)
- [データサイエンス環境構築ガイド](https://jakevdp.github.io/blog/2017/12/05/installing-python-packages-from-jupyter/)

### コミュニティ
- [uv GitHub Issues](https://github.com/astral-sh/uv/issues)
- [Jupyter Community](https://jupyter.org/community)
- [Python Packaging User Guide](https://packaging.python.org/)

---

この記事が、uvとJupyter Notebookを使った効率的な開発環境構築の参考になれば幸いです。質問や改善提案があれば、お気軽にお声かけください。 

# まとめ
Claude 4 Sonnetすげえ。

Cursorで一緒にjupyter notebookでuv使えるようにセットアップして、そのチャットの最後に

「uvで作成した仮想環境でjupyter notebookを実行する方法っていう記事にしたい。構成を考えて提案して」

って伝えて、良さげな目次が出てきたから

「OKです。実際に中の文章も加えて、 uv_jupyter.mdというファイル名で作成してください。階層は今の階層でいいです」

って言ったらこれ。便利やなぁ。

この記事いいなって思ったらいいね頼むで。Claude 4 Sonnetのために。