uv でプロジェクトを作り、その仮想環境を VS Code の Jupyter Notebook で使う手順をまとめました。
ipykernel のインストールから、VS Code 上でカーネルを選ぶまでをステップで説明します。公式ドキュメントをベースにした備忘録です。
うまくいかないときは後半のトラブルシュートも見てください。
この記事でわかること
- uv で作った仮想環境を Jupyter で使う流れ
- ipykernel の役割と、カーネル登録のコマンド
- VS Code で Jupyter カーネルを選択する手順
- カーネルが出ない/PATH/間違った環境を選んだときの切り分け
前提条件
- Pythonをインストール済み
- uv がインストール済み(インストール方法)
開発環境
- macOS Sequoia 15.5
- VS Code
- zsh 5.9 (arm64-apple-darwin24.0)
1. プロジェクトフォルダの作成
uv init projectname
cd projectname2. uv で Jupyter(ipykernel)を入れてカーネルを登録する
uv add --dev ipykernel
uv run ipython kernel install --user --env VIRTUAL_ENV $(pwd)/.venv --name=KERNEL_NAMEKERNEL_NAME は任意の名前(例: my-uv-env)にしてください。
Jupyter をサーバーとしてローカルで起動したい場合は、次のようにします。
uv run --with jupyter jupyter lab3. .ipynb ファイルを作成する
VS Code で Create: New Jupyter Notebook と入力して、新しい Jupyter ノートブックを作成します。

4. VS Code でカーネルを選ぶ
ノートブックを開いた状態で、右上のカーネル選択から 2 で登録したカーネル を選びます。

- 一覧にない場合は 「その他のカーネルを選択」→「Jupyter Kernel」→ 作成したカーネル名 を選びます。

カーネルが一覧に出ない場合
「その他のカーネルを選択」→「Jupyter Kernel」→ 自分の作成したカーネルを選択します。

5. 動作確認
ノートに次のコードを入れて実行し、どの venv が有効か確認できます。
import sys
print(f"Python version: {sys.version}")
print(f"Virtual environment: {sys.prefix}")
.venv のパスが表示されていれば、uv で作った環境が Jupyter で使えています。

うまくいかないとき
uv コマンドが見つからない
ターミナルで uv --version が通らないときは、まずインストールと PATH を疑います。
# 公式のインストール手順を確認
# https://docs.astral.sh/uv/getting-started/installation/
which uv
echo $PATH新しいターミナルを開き直してもダメなら、シェル設定(~/.zshrc など)に PATH が通っているかを見てください。
僕も一度、別ターミナルでは動くのに VS Code の統合ターミナルだけ古い PATH のまま、ということがありました。
カーネルが一覧に表示されない
登録済みカーネルを確認します。
uv run jupyter kernelspec list表示された KERNEL_NAME を、VS Code の「その他のカーネルを選択」から探します。
それでも出ないときは、次も試します。
- VS Code を一度リロード(Command Palette →
Developer: Reload Window) - Python 拡張と Jupyter 拡張が入っているか
- ノートブック右上で「その他のカーネルを選択」→「Jupyter Kernel」まで潜る(一覧の先頭に出ないことがある)
間違ったインタプリタ/カーネルを選んでいる
一覧に似た名前が並ぶと、グローバルの Python や別プロジェクトの .venv を選びがちです。
動作確認用のセルで sys.prefix を出し、今のプロジェクトの .venv パスになっているか見てください。
import sys
print(sys.prefix)違うパスなら、カーネル選択をやり直します。
カーネル名の付け方・上書き
ipython kernel install ... --name=KERNEL_NAME の名前は、自分が後から見分けられる短い名前がよいです。
同じ名前でもう一度登録すると上書きっぽい挙動になるので、迷ったら別名で登録し直すか、下の削除コマンドで消してから入れ直します。
カーネルを削除したい
uv run jupyter kernelspec uninstall KERNEL_NAMEまとめ
- uv で
uv initしたプロジェクトに ipykernel を入れ、ipython kernel installでカーネル登録すると、VS Code の Jupyter からその仮想環境を選べます。 - カーネルが出てこないときは
jupyter kernelspec listで登録名を確認し、VS Code 側で「Jupyter Kernel」から選び直すとよいです。 - PATH・拡張・リロード・
sys.prefixの確認までやると、だいたい原因が切り分けられます。