【環境構築】uvからJupyterLabを起動する

# 0. はじめに

この記事は初学者を対象に、**Pythonパッケージ管理ツールuvを使ってJupyterLabで開発する環境を構築する手順**を紹介します。

# 1. 開発環境

私が行なった環境構築は以下の通りです。

- OS
    - macOS Sequoia 15.5
- バージョン/パッケージマネージャー
    - uv 0.7.8
- エディター
    - JupyterLab 4.4.3
- リンター/フォーマッター
    - Ruff 0.11.11
- 型チェッカー
    - なし

記事を読んで上手くいかなかったときは、こちらに記載のバージョンに合わせていただくと上手くいくと思います。

uvを用いてバージョンを変更する方法は、[colum2131](https://zenn.dev/colum2131)さんの記事「[uvだけでPythonプロジェクトを管理する](https://zenn.dev/turing_motors/articles/594fbef42a36ee#1.5-python%E3%83%90%E3%83%BC%E3%82%B8%E3%83%A7%E3%83%B3%E5%A4%89%E6%9B%B4)」をご参考にしてみてください。

# 2. 構築手順

MacのCLIであるターミナルを用いて以下の**2.1. uvをインストール 〜 2.3. Jupyter Labを起動**を順番に実行してください。

<details>
  <summary>
      <font color="#b3b3b3">CLIとは</font>
  </summary>
  
CLI（Command Line Interface）とは、コンピュータ操作をコマンド入力により行う方法。詳細は[IT用語時点を参照](https://e-words.jp/w/CLI.html)。
</details>

## 2.1. uvをインストール

Pythonパッケージ管理ツールuvをインストールします。

```:uvをインストール
curl -LsSf https://astral.sh/uv/install.sh | sh
```

実行してインストールが成功すると、次のような実行結果が表示されます。

```:実行結果
downloading uv 0.7.8 x86_64-apple-darwin no checksums to verify
installing to /Users/[ユーザー名]/.local/bin
    uv
    UV X
everything's installed!
To add $HOME/.local/bin to your PATH, either restart your shell or run:
    source SHOME/. local/bin/env (sh, bash, zsh) 
    source $HOME/.local/bin/env.fish (fish)
```

<details>
  <summary>
      <font color="#b3b3b3">uvのバージョンの確認方法</font>
  </summary>

```:uvのバージョンの確認方法
uv --version
```

</details>

### 2.1.1. ターミナルの更新

インストールが完了したら、次のコマンドで一度ターミナルを更新してください。

```:ターミナルの更新
source .zshrc
```

## 2.2. uvでプロジェクトを作成

次はPythonのプロジェクトをuvを用いて作成します。

```:uvでプロジェクトを作成
cd [プロジェクトを作成したいディレクトリ]
uv init [プロジェクト名]
```

<details>
  <summary>
      <font color="#b3b3b3">ディレクトリとは</font>
  </summary>

フォルダのことです。慣れない方は「ディレクトリ」を「フォルダ」に置き換えて読み進めてみてください。
参考資料：[「分かりそう」で「分からない」でも「分かった」気になれるIT用語辞典](https://wa3.i-3-i.info/word199.html)
</details>

実行すると次のような結果が表示されます。

```:実行結果
Initialized project '[プロジェクト名]'
at '[プロジェクトを作成したいディレクトリ]/[プロジェクト名]'
```

以上でプロジェクトの作成は完了です。

2.2.1〜2.2.6は仮想環境の設定、リンター/フォーマッターの追加について説明しています。
不要な方は[2.3. Jupyter Labを起動](#23-jupyter-labを起動)まで移動してください。

### 2.2.1. 仮想環境を設定

venvを用いて仮想環境の設定を行なっていきます。

参考資料：[【Python】なぜ仮想環境が必要なのか（初心者向け）](https://qiita.com/Neckoh/items/c6ddf8b800bd67fa9435)

### 2.2.2. 作成したプロジェクトディレクトリに移動

仮想環境を作りたいプロジェクトのディレクトリに移動してください。

```:
cd [プロジェクトのあるディレクトリ]
```

### 2.2.3. 仮想環境を追加

以下のコマンドを実行して、仮想環境を設定するための.venvディレクトリを作成します。

```:仮想環境を追加
uv venv
```

:::note warn
**venvディレクトリは隠しディレクトリ**

venvディレクトリは隠しディレクトリなので`ls`でディレクトリ一覧を表示させても出てきません。

```:lsを実行
% cd [プロジェクト名のディレクトリ]
% ls
main.py		pyproject.toml	README.md	sample_nb.ipynb	uv.lock
```

`-a`オプションをつけると確認することができます。

```:ls -aを実行
% cd [プロジェクト名のディレクトリ]
% ls -a
.		.python-version	main.py		README.md
..		.venv		pyproject.toml
```
:::


### 2.2.4. 仮想環境を有効化

.venvディレクトリを作成しただけでは仮想環境を設定したことにはなりません。以下のコマンドを実行し、有効化することで設定完了となります。

```:仮想環境を有効化
. .venv/bin/activate
```

### 2.2.5. リンター/フォーマッターを追加

リンター兼フォーマッターとしてruffを設定します。

参考資料：[Pythonのリンター・フォーマッターをしっかりと理解する（Flake8, Black, isort, mypy）](https://zenn.dev/tanny/articles/cdb555d6124a2a)

作成した**プロジェクト名のディレクトリの中**に移動してください。

```:
cd [プロジェクト名のディレクトリ]
```

ruffをインストールします。

```:リンター/フォーマッターを追加（ruff）
uv add ruff --dev
```

<details>
  <summary>
    <font color="#b3b3b3">コマンド解説</font>
  </summary>

- **uv add**：プロジェクトに新しい依存関係を追加する。これによりpyproject.tomlやrequirements.txtにパッケージを追加することができる。
- **--dev** オプション：追加するパッケージやツールを開発用の依存関係としてインストールする。
</details>

実行結果は次のようになります。

```:実行結果
Using Python 3.9.6 interpreter at: /Library/Developer/CommandLineTools/usr/bin/ python3
Creating virtual environment at: .venv
Resolved 2 packages in 362ms
Prepared 1 package in 2.38s Installed 1 package in 3ms 
 + ruff==0.11.11
```


### 2.2.6. プロジェクトのカーネルを作成

プロジェクトごとにカーネルを作成することで、notebook内でインストールしたパッケージがプロジェクトの仮想環境に追加されるようになります。

まずは作成した**プロジェクト名のディレクトリの中**に移動してください。移動済みならこのコマンドは飛ばしてください。

```:
cd [プロジェクト名のディレクトリ]
```

ipykernelをインストールします。

```:プロジェクトのカーネルを作成
uv add ipykernel --dev
```

実行結果は次のようになります。

```:実行結果
Resolved 42 packages in 887ms
Prepared 33 packages
in 2.18s
Installed 33 packages in 81ms + appnope==0.1.4
+ asttokens==3.0.0
+ comm==0.2.2
+ debugpy==1.8.14
+ decorator==5.2.1
+ exceptiongroup==1.3.0
+ executing==2.2.0
+ importlib-metadata==8.7.0
+ ipykernel==6.29.5
+ ipython==8.18.1
+ jedi==0.19.2
+ jupyter-client==8.6.3
+ jupyter-core==5.8.1
+ matplotlib-inline==0.1.7
+ nest-asyncio==1.6.0
+ packaging==25.0
+ parso==0.8.4
+ pexpect==4.9.0
+ platformdirs==4.3.8
+ prompt-toolkit==3.0.51
+ psutil==7.0.0
+ ptyprocess==0.7.0
+ pure-eval==0.2.3
+ pygments==2.19.1
+ python-dateutil==2.9.0.post0
+ pyzmq==26.4.0
+ six==1.17.0
+ stack-data==0.6.3
+ tornado==6.5.1
+ traitlets==5.14.3
+ typing-extensions==4.13.2
+ wcwidth==0.2.13
+ zipp==3.22.0
```

次に、プロジェクト名のカーネルを登録します。

```:
uv run ipython kernel install --user --name=[プロジェクト名のカーネル]
```

<details>
  <summary>
    <font color="#b3b3b3">コマンド解説</font>
  </summary>

- **ipython**：Jupyterの中核となる対話型シェル。
- **kernel**：ipythonのサブコマンドで、Jupyterカーネルに関連する操作を行う。
- **install**：ipython kernelのサブコマンドで、新しいカーネルをJupyterに登録する。
- **--userオプション**：カーネルを現在のユーザーのJupyterカーネルディレクトリにインストールすることを指示する。これにより、他のユーザーのJupyter環境には影響を与えずに自分だけがそのカーネルを利用できるようになる。
</details>

実行結果は次のようになります。

```:実行結果
Installed kernelspec sample_project in [プロジェクト名のディレクトリ]
```

<details>
  <summary>
    <font color="#b3b3b3">カーネルの削除方法</font>
  </summary>

なお、作成したカーネルを削除する場合は以下のコマンドを用います。

```:作成したカーネルを削除する
uv run --with jupyter jupyter kernelspec uninstall [プロジェクト名のカーネル]

```

</details>

## 2.3. Jupyter Labを起動

それではいよいよJupyter Labを起動していきます。

### 2.3.1 Jupyter Labをインストール

作成した**プロジェクト名のディレクトリの中**に移動してください。移動済みならこのコマンドは飛ばしてください。

```:
cd [プロジェクト名のディレクトリ]
```

Jupyter Labをインストールします。以下のコマンドを実行してください。

```:Jupyter Labをインストール
uv add jupyterlab
```

### 2.3.2. Jupyter Labを起動

あとは以下のコマンドを実行すれば起動します。

```:Jupyter Labを起動
uv run --with jupyter jupyter lab
```

<details>
  <summary>
    <font color="#b3b3b3">コマンド解説</font>
  </summary>

- **--with jupyter**：uvのオプションで、jupyter関連のパッケージ（jupyterlab、notebook、ipykernelなど）を自動的に仮想環境にインストールし、JupyterLabがその仮想環境を利用できるように設定する。
- **jupyter lab**：仮想環境内で実行される実際のコマンド。このコマンドがJupyterLabアプリケーションを起動する。
</details>

![スクリーンショット 2025-06-06 12.58.10.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/4010745/e127d811-9512-48ad-855f-79275a896cd1.png)


## 2.4. 2回目以降のJupyter Labの起動方法

一度プロジェクトを作成したら、次回以降は次のコマンド入力のみでJupyter Lab操作画面まで行えるようになります。

```:2回目以降のJupyter Labの起動
cd [プロジェクト名のディレクトリ]
uv run jupyter lab
```

## 2.5. Jupyter Labの拡張機能など

最後に個人的におすすめな追加機能および設定を紹介します。

### 2.5.1. JupyterLab Code Formatter

JupyterLab Code Formatterは標準搭載の設定よりもより細かな設定が可能になります。

```:jupyterlab-code-formatterをインストールする
cd [プロジェクト名のディレクトリ]
uv add jupyterlab-code-formatter
```

```:実行結果
Resolved 104 packages in 859ms
Installed 1 package in 15ms
 + jupyterlab-code-formatter==3.0.2
```
「設定」→「Setting Editor」に移動すると、Jupyterlab Code Formatterを確認することができます。

![スクリーンショット 2025-06-06 12.29.43.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/4010745/11d9d815-439b-425d-bb58-3b86296052f6.png)

### 2.5.2. gitignore

個人的におすすめというより、もはやマストかもしれません。

開発者の皆さんの多くはgitツールを用いてソースコード等をバージョン管理することになると思いますが、その際にgit管理する必要のないものや、してはいけないものなどがあり、それらをpushするたびに手作業で取り除くのは効率が悪く、最悪の場合pushしてはいけないファイル（envファイルなど）を誤ってpushしてしまうリスクを生み出してしまいます。このようなことが起こらないようにpush時に自動的に指定したディレクトリ（ファイル）を無視する設定ファイルがgitignoreです。

ここでは実際に私が使用した内容を例にご紹介します。

**.gitignoreファイルの作成**

.gitignoreファイルを作成したい場所（今回はプロジェクト内のディレクトリ）に移動して、以下のコマンドを実行します。

```:.gitignoreファイルの作成
touch .gitignore
```

そのあと、必要に応じた記述を.gitignore内に記述して保存します。

![スクリーンショット 2025-06-20 14.56.30.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/4010745/889e1609-1f4d-4a0b-b7ca-a3917d986804.png)

記述方法については、[@TaikiTkwkbysh(WAKA Engineer)](https://qiita.com/TaikiTkwkbysh)さんのQiita記事「[.gitignoreファイルによる除外方法](https://qiita.com/TaikiTkwkbysh/items/1a7d328922e9486a71a6)」をご参考になさってください。


### 2.5.3. nbstripout

github等で管理する場合、出力結果も一緒にpushしてしまうと本質的な差分確認がしづらい等の不便さが発生します。そんなときnbstripoutを設定すると、githubのcommit時に自動で実行結果を消去してくれます。

**インストール**
```:インストール
cd [プロジェクト名のディレクトリ]
uv add nbstripout
```

インストールが完了したら、以下のコマンドを実行してJupyterLabの出力がcommit時に自動で削除されるように設定されます。

```:JupyterLabの出力をcommit時に自動削除
uv run nbstripout --install --attributes .gitattributes
```

実行すると、プロジェクトディレクトリ内に「.gitattributes」というファイルが作成され、次のような内容が記述されました。

![スクリーンショット 2025-06-20 14.38.17.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/4010745/38207786-f3ef-4462-ac7f-d5e826ca122f.png)


### 2.5.4. JupyterLab Language Pack ja-Jp

標準搭載の言語は英語のみですが、JupyterLab Language Pack ja-Jpを使うと、日本語で表示されます。
※ただし、一部の表示は英語のままです。

**インストール**
```:インストール
uv add jupyterlab-language-pack-ja-Jp
```

以下のような実行結果が出ます。

```:実行結果
Resolved 128 packages in 782ms
Prepared 1 package in 86ms
Installed 1 package in 8ms
 + jupyterlab-language-pack-ja-jp==4.4.post0
```

JupyterLabを更新すると、自動的に日本語設定に変更されました。

![スクリーンショット 2025-06-06 10.52.33.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/4010745/7a1a02bf-dcbb-40c9-a44c-c7e97c9a1e71.png)

その他の拡張機能については[のこのこ](https://qiita.com/nokonoko_1203
)さんの以下の記事が参考になりますので、気になる方はご覧ください。

https://qiita.com/nokonoko_1203/items/edd010616a74468ea531

### 2.5.5. jupyterlab-toc

Markdownの見出しをもとに目次を表示する拡張機能ですが、**<font color="red">インストールしなくて良い</font>** です。JupyterLabのバージョン3.x以降では標準で組み込まれています。

![スクリーンショット 2025-06-06 12.27.44.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/4010745/5d31f74a-47b5-4dc3-9f51-27d63ad62871.png)


いかがだったでしょうか。
環境構築は慣れないと苦戦しますよね。かといって環境構築は初学者の時点で割と真っ先に向き合わないといけない部分で、越えなきゃいけない山がいっぱいな難所で…。

この記事が、新しい一歩を踏み出そうとしているどなたかの一助になれば嬉しいです。

# 参考資料

環境構築および記事作成にあたり、以下のサイトを参考にさせて頂きました。心より感謝申し上げます。

**【uv公式ドキュメント】**
- [Using uv with Jupyter](https://docs.astral.sh/uv/guides/integration/jupyter/)
- [Project structure](https://docs.astral.sh/uv/guides/projects/#project-structure)

**【Ruff公式ドキュメント】**
- [Configuring Ruff](https://docs.astral.sh/ruff/configuration/)

**【Zenn】**
- [【Python仮想環境管理】uv コマンド&引数一覧と機能概要](https://zenn.dev/lia/articles/bc31feaf3a4715)
- [uvだけでPythonプロジェクトを管理する](https://zenn.dev/turing_motors/articles/594fbef42a36ee)
- [uvでjupyter labを起動する](https://zenn.dev/eastxe/articles/c03468773c04b6)
- [Pythonのリンター・フォーマッターをしっかりと理解する](https://zenn.dev/tanny/articles/cdb555d6124a2a)
- [【補足編】Ruffの設定方法とコマンド解説](https://zenn.dev/egg_glass/books/flet-development-practical/viewer/ruff)
- [Rust製の高速Linter・Formatter「Ruff」の初心者向け解説](https://zenn.dev/mkj/articles/4e6833e71b267c)

**【Qiita】**
- [2020年5月におけるPython開発環境の選択肢](https://qiita.com/nicco_mirai/items/80ba4b4bf9db11ac54c6)
- [【Python】なぜ仮想環境が必要なのか（初心者向け）](https://qiita.com/Neckoh/items/c6ddf8b800bd67fa9435)
- [venv: Python 仮想環境管理](https://qiita.com/fiftystorm36/items/b2fd47cf32c7694adc2e)
- [venvによる仮想環境の作り方](https://qiita.com/futakuchi0117/items/6030458a96f62cb64d37)
- [venvで手軽にPythonの仮想環境を構築しよう](https://qiita.com/shun_sakamoto/items/7944d0ac4d30edf91fde)
- [総合開発環境(IDE)とは何か？初心者におすすめの4つのIDEを紹介](https://qiita.com/EasyCoder/items/81cf7674235a7a19d69c)
- [uv （pythonパッケージマネージャー）の使い方　簡易版](https://qiita.com/futakuchi0117/items/9ec8bd84797fed180647)
- [UVを使ったJupyterlabの起動方法](https://qiita.com/jun1-yossy/items/db9ca75880560724c77b)
- [Pythonのプロジェクト・パッケージ管理ツール uv の使用方法メモ](https://qiita.com/takashiuesaka/items/89143a944e514168c938)
- [JupyterLabのすゝめ](https://qiita.com/kirikei/items/a1639954ce5ccaf7ac3c)
- [JupyterLabのおすすめ拡張機能9選](https://qiita.com/canonrock16/items/d166c93087a4aafd2db4)
- [Pythonの型ヒントと静的型チェッカー（mypy）の活用方法](https://qiita.com/Tadataka_Takahashi/items/300d99bb42ec1df719f3)
- [jupyter labで最低限これだけは入れとけっていう拡張機能の紹介！](https://qiita.com/nokonoko_1203/items/edd010616a74468ea531)
- [[VSCode] Ruffの設定メモ](https://qiita.com/BlueSilverCat/items/f44a0253609673c5fdbb)
- [Jupyter Notebookを出力を無視してgit管理する方法](https://qiita.com/ctyl/items/bbc04e0b0bd4557d54a6)
- [.gitignoreファイルによる除外方法](https://qiita.com/TaikiTkwkbysh/items/1a7d328922e9486a71a6)

**【その他HP】**
- [Pythonの開発環境を用意しよう！](https://prog-8.com/docs/python-env)
- [さらなる進化を遂げた「uv」の新機能](参考資料：https://gihyo.jp/article/2024/09/monthly-python-2409)
- [「分かりそう」で「分からない」でも「分かった」気になれるIT用語辞典](https://wa3.i-3-i.info/word199.html)