リンクをコピーしました

uv でプロジェクトを作り、その仮想環境を VS Code の Jupyter Notebook で使う手順をまとめました。
ipykernel のインストールから、VS Code 上でカーネルを選ぶまでをステップで説明します。公式ドキュメントをベースにした備忘録です。
うまくいかないときは後半のトラブルシュートも見てください。

この記事でわかること

  • uv で作った仮想環境を Jupyter で使う流れ
  • ipykernel の役割と、カーネル登録のコマンド
  • VS Code で Jupyter カーネルを選択する手順
  • カーネルが出ない/PATH/間違った環境を選んだときの切り分け

前提条件

開発環境

  • macOS Sequoia 15.5
  • VS Code
  • zsh 5.9 (arm64-apple-darwin24.0)

1. プロジェクトフォルダの作成

uv init projectname
cd projectname

2. uv で Jupyter(ipykernel)を入れてカーネルを登録する

uv add --dev ipykernel
uv run ipython kernel install --user --env VIRTUAL_ENV $(pwd)/.venv --name=KERNEL_NAME

KERNEL_NAME は任意の名前(例: my-uv-env)にしてください。

Jupyter をサーバーとしてローカルで起動したい場合は、次のようにします。

uv run --with jupyter jupyter lab

3. .ipynb ファイルを作成する

VS Code で Create: New Jupyter Notebook と入力して、新しい Jupyter ノートブックを作成します。

VS CodeでJupyterノートブックを新規作成

4. VS Code でカーネルを選ぶ

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

VS Codeでカーネルを選択
  • 一覧にない場合は 「その他のカーネルを選択」→「Jupyter Kernel」→ 作成したカーネル名 を選びます。
カーネル一覧で登録したカーネルを選択
カーネルが一覧に出ない場合

「その他のカーネルを選択」→「Jupyter Kernel」→ 自分の作成したカーネルを選択します。

その他のカーネルを選択してJupyter Kernelを選ぶ

5. 動作確認

ノートに次のコードを入れて実行し、どの venv が有効か確認できます。

import sys

print(f"Python version: {sys.version}")
print(f"Virtual environment: {sys.prefix}")
ノートの起動テスト

.venv のパスが表示されていれば、uv で作った環境が Jupyter で使えています。

環境確認(sys.version と sys.prefix)

うまくいかないとき

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 の確認までやると、だいたい原因が切り分けられます。

参考リンク