0. はじめに
この記事は初学者を対象に、Pythonパッケージ管理ツールuvを使ってJupyterLabで開発する環境を構築する手順を紹介します。
1. 開発環境
私が行なった環境構築は以下の通りです。
- OS
- macOS Sequoia 15.5
- バージョン/パッケージマネージャー
- uv 0.7.8
- エディター
- JupyterLab 4.4.3
- リンター/フォーマッター
- Ruff 0.11.11
- 型チェッカー
- なし
記事を読んで上手くいかなかったときは、こちらに記載のバージョンに合わせていただくと上手くいくと思います。
uvを用いてバージョンを変更する方法は、colum2131さんの記事「uvだけでPythonプロジェクトを管理する」をご参考にしてみてください。
2. 構築手順
MacのCLIであるターミナルを用いて以下の2.1. uvをインストール 〜 2.3. Jupyter Labを起動を順番に実行してください。
CLIとは
CLI（Command Line Interface）とは、コンピュータ操作をコマンド入力により行う方法。詳細はIT用語時点を参照。
2.1. uvをインストール
Pythonパッケージ管理ツール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)
uvのバージョンの確認方法
uv --version
2.1.1. ターミナルの更新
インストールが完了したら、次のコマンドで一度ターミナルを更新してください。
source .zshrc
2.2. uvでプロジェクトを作成
次はPythonのプロジェクトをuvを用いて作成します。
cd [プロジェクトを作成したいディレクトリ]
uv init [プロジェクト名]
ディレクトリとは
フォルダのことです。慣れない方は「ディレクトリ」を「フォルダ」に置き換えて読み進めてみてください。
参考資料：「分かりそう」で「分からない」でも「分かった」気になれるIT用語辞典
実行すると次のような結果が表示されます。
Initialized project '[プロジェクト名]'
at '[プロジェクトを作成したいディレクトリ]/[プロジェクト名]'
以上でプロジェクトの作成は完了です。
2.2.1〜2.2.6は仮想環境の設定、リンター/フォーマッターの追加について説明しています。
不要な方は2.3. Jupyter Labを起動まで移動してください。
2.2.1. 仮想環境を設定
venvを用いて仮想環境の設定を行なっていきます。
参考資料：【Python】なぜ仮想環境が必要なのか（初心者向け）
2.2.2. 作成したプロジェクトディレクトリに移動
仮想環境を作りたいプロジェクトのディレクトリに移動してください。
cd [プロジェクトのあるディレクトリ]
2.2.3. 仮想環境を追加
以下のコマンドを実行して、仮想環境を設定するための.venvディレクトリを作成します。
uv venv
venvディレクトリは隠しディレクトリ
venvディレクトリは隠しディレクトリなのでlsでディレクトリ一覧を表示させても出てきません。
% cd [プロジェクト名のディレクトリ]
% ls
main.py pyproject.toml README.md sample_nb.ipynb uv.lock
-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）
作成したプロジェクト名のディレクトリの中に移動してください。
cd [プロジェクト名のディレクトリ]
ruffをインストールします。
uv add ruff --dev
コマンド解説
- uv add：プロジェクトに新しい依存関係を追加する。これによりpyproject.tomlやrequirements.txtにパッケージを追加することができる。
- --dev オプション：追加するパッケージやツールを開発用の依存関係としてインストールする。
実行結果は次のようになります。
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=[プロジェクト名のカーネル]
コマンド解説
- ipython：Jupyterの中核となる対話型シェル。
- kernel：ipythonのサブコマンドで、Jupyterカーネルに関連する操作を行う。
- install：ipython kernelのサブコマンドで、新しいカーネルをJupyterに登録する。
- --userオプション：カーネルを現在のユーザーのJupyterカーネルディレクトリにインストールすることを指示する。これにより、他のユーザーのJupyter環境には影響を与えずに自分だけがそのカーネルを利用できるようになる。
実行結果は次のようになります。
Installed kernelspec sample_project in [プロジェクト名のディレクトリ]
カーネルの削除方法
なお、作成したカーネルを削除する場合は以下のコマンドを用います。
uv run --with jupyter jupyter kernelspec uninstall [プロジェクト名のカーネル]
2.3. Jupyter Labを起動
それではいよいよJupyter Labを起動していきます。
2.3.1 Jupyter Labをインストール
作成したプロジェクト名のディレクトリの中に移動してください。移動済みならこのコマンドは飛ばしてください。
cd [プロジェクト名のディレクトリ]
Jupyter Labをインストールします。以下のコマンドを実行してください。
uv add jupyterlab
2.3.2. Jupyter Labを起動
あとは以下のコマンドを実行すれば起動します。
uv run --with jupyter jupyter lab
コマンド解説
- --with jupyter：uvのオプションで、jupyter関連のパッケージ（jupyterlab、notebook、ipykernelなど）を自動的に仮想環境にインストールし、JupyterLabがその仮想環境を利用できるように設定する。
- jupyter lab：仮想環境内で実行される実際のコマンド。このコマンドがJupyterLabアプリケーションを起動する。
2.4. 2回目以降のJupyter Labの起動方法
一度プロジェクトを作成したら、次回以降は次のコマンド入力のみでJupyter Lab操作画面まで行えるようになります。
cd [プロジェクト名のディレクトリ]
. .venv/bin/activate && uv run jupyter lab
2.5. Jupyter Labの拡張機能など
最後に個人的におすすめな追加機能および設定を紹介します。
2.5.1. 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を確認することができます。
2.5.2. gitignore
個人的におすすめというより、もはやマストかもしれません。
開発者の皆さんの多くはgitツールを用いてソースコード等をバージョン管理することになると思いますが、その際にgit管理する必要のないものや、してはいけないものなどがあり、それらをpushするたびに手作業で取り除くのは効率が悪く、最悪の場合pushしてはいけないファイル（envファイルなど）を誤ってpushしてしまうリスクを生み出してしまいます。このようなことが起こらないようにpush時に自動的に指定したディレクトリ（ファイル）を無視する設定ファイルがgitignoreです。
ここでは実際に私が使用した内容を例にご紹介します。
.gitignoreファイルの作成
.gitignoreファイルを作成したい場所（今回はプロジェクト内のディレクトリ）に移動して、以下のコマンドを実行します。
touch .gitignore
そのあと、必要に応じた記述を.gitignore内に記述して保存します。
記述方法については、@TaikiTkwkbysh(WAKA Engineer)さんのQiita記事「.gitignoreファイルによる除外方法」をご参考になさってください。
設定したいファイルがすでにGitのリポジトリに追跡されている場合
.gitignoreは Gitがまだ追跡していないファイルを対象としているため、プロジェクト内に移動して、以下のコマンドを実行してリモートリポジトリのファイルを削除します。
git rm -rf --cached .ipynb_checkpoints
2.5.3. nbstripout
github等で管理する場合、出力結果も一緒にpushしてしまうと本質的な差分確認がしづらい等の不便さが発生します。そんなときnbstripoutを設定すると、githubのcommit時に自動で実行結果を消去してくれます。
インストール
cd [プロジェクト名のディレクトリ]
uv add nbstripout
インストールが完了したら、以下のコマンドを実行してJupyterLabの出力がcommit時に自動で削除されるように設定されます。
uv run nbstripout --install --attributes .gitattributes
コマンド解説
- --install オプション：nbstripout を Git のフックとしてインストールするよう指示する。つまり Git のリポジトリの .git/config ファイルに設定を追加し、git add や git commit コマンドが実行される際に、自動的に nbstripout が適用されるようにする。
- --attributes .gitattributes オプション：nbstripout をどのファイルに適用するかを .gitattributes ファイルに設定するよう指示する。
実行すると、プロジェクトディレクトリ内に「.gitattributes」というファイルが作成され、次のような内容が記述されます。
また、nbstripoutがインストールされているディレクトリが、システムのPARH環境変数に含まれていることをターミナルで確認します。
which nbstripout
実行結果が次のように出力されていれば完了です。
[プロジェクトのディレクトリ]/.venv/bin/nbstripout
PATH環境変数に含まれていない場合
シェル設定ファイルを編集して、PARH環境変数に追加します。この記事ではZshの設定方法を記述します。
1: npstripoutまでのパスを取得する
作成したプロジェクト内の「.venv/bin」の中にnpstripoutがあることを確認し、binディレクトリのパスをコピーします。
2: ターミナルでエディタを開く
nano ~/.zshrc
3: 開いたエディタ内で、以下を入力する
export PATH="[プロジェクトのディレクトリ]/.venv/bin:$PATH"
4: [Ctrl]キー + O、[Enter]キーで入力内容を保存する
5: [Ctrl]キー + Xでエディタを終了する
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を更新すると、自動的に日本語設定に変更されました。
その他の拡張機能についてはのこのこさんの以下の記事が参考になりますので、気になる方はご覧ください。
2.5.5. jupyterlab-toc
Markdownの見出しをもとに目次を表示する拡張機能ですが、インストールしなくて良い です。JupyterLabのバージョン3.x以降では標準で組み込まれています。
いかがだったでしょうか。
環境構築は慣れないと苦戦しますよね。かといって環境構築は初学者の時点で割と真っ先に向き合わないといけない部分で、越えなきゃいけない山がいっぱいな難所で…。
この記事が、新しい一歩を踏み出そうとしているどなたかの一助になれば嬉しいです。
参考資料
環境構築および記事作成にあたり、以下のサイトを参考にさせて頂きました。心より感謝申し上げます。
【uv公式ドキュメント】
【Ruff公式ドキュメント】
【Zenn】
- 【Python仮想環境管理】uv コマンド&引数一覧と機能概要
- uvだけでPythonプロジェクトを管理する
- uvでjupyter labを起動する
- Pythonのリンター・フォーマッターをしっかりと理解する
- 【補足編】Ruffの設定方法とコマンド解説
- Rust製の高速Linter・Formatter「Ruff」の初心者向け解説
- Jupyter NotebookをGitで管理する方法
【Qiita】
- 2020年5月におけるPython開発環境の選択肢
- 【Python】なぜ仮想環境が必要なのか（初心者向け）
- venv: Python 仮想環境管理
- venvによる仮想環境の作り方
- venvで手軽にPythonの仮想環境を構築しよう
- 総合開発環境(IDE)とは何か？初心者におすすめの4つのIDEを紹介
- uv （pythonパッケージマネージャー）の使い方 簡易版
- UVを使ったJupyterlabの起動方法
- Pythonのプロジェクト・パッケージ管理ツール uv の使用方法メモ
- JupyterLabのすゝめ
- JupyterLabのおすすめ拡張機能9選
- Pythonの型ヒントと静的型チェッカー（mypy）の活用方法
- jupyter labで最低限これだけは入れとけっていう拡張機能の紹介！
- [VSCode] Ruffの設定メモ
- Jupyter Notebookを出力を無視してgit管理する方法
- .gitignoreファイルによる除外方法
【その他HP】