はじめに #
Pythonのパッケージ管理ツールuvの使用方法を解説するシリーズの第1段です。 uvでPythonのプロジェクトを新しく開始する方法を解説します。
検証環境は以下の通りです。
- Windows 10 Home 22H2
- uv 0.8.13
この記事では、uvの以下のコマンドについて解説します。
uv init: Pythonのプロジェクトを作る。仮想環境は構築しないuv sync:pyproject.tomlからライブラリを含む仮想環境を構築するuv venv:pyproject.tomlがない状況で仮想環境を構築する
システム構成 #
uvを使用したスタンダードなシステム構成は以下の図のようになります。 PC上にuvを1つだけインストールし、複数の仮想環境を構築できます。 各仮想環境には、異なるバージョンのPythonや、ライブラリ（NumPyなど）をインストールできます。
block-beta columns 3 p13["Python 3.13"] p12["Python 3.12"] p12a["Python 3.12"] 仮想環境1 仮想環境2 仮想環境3 uv:3 OS:3
uvのインストール #
以下の公式ページに従ってuvをインストールします。
なお、uvはシングルバイナリで動作するため、以下の手順でも使用できます。
- GitHubのuvのReleasesページから対応するuvをダウンロードする。
- 圧縮ファイルを展開し、
uv.exeなどを適当なフォルダに置いてパスを通す。
適用なフォルダで以下のコマンドを実行して、uvのバージョンが表示されることを確認します。
uv -V
プロジェクトの作成 #
uvでPythonのプロジェクトを作成するには、以下のコマンドを実行します。
uv init [PATH]
[PATH]はプロジェクトの名称とします。
なお、プロジェクトの性質によって以下のオプションを付けます。
--app: Webアプリなど自己完結したアプリケーションを作成（デフォルト）--lib: Pythonのライブラリを作成--script: 単一のPythonスクリプトを作成
uv initに何もオプションを付けない場合、--appと同じ挙動になります。
各オプションで作成されるフォルダ構造を以下に示します。
appオプション #
uv init --app [PATH]を実行した場合、以下の構造のフォルダが作成されます。
.git/
.gitignore
.python-version
main.py
pyproject.toml
README.md
libオプション #
uv init --lib [PATH]を実行した場合、以下の構造のフォルダが作成されます。
いわゆるsrc-layoutのフォルダ構造です。
.git/
src/
└[PATH]/
├__init__.py
└py.typed
.gitignore
.python-version
pyproject.toml
README.md
scriptオプション #
uv init --script [PATH]を実行した場合、フォルダは作成されず、Pythonスクリプトが1個だけ作成されます。
そのため、[PATH]はhoge.pyのように拡張子.pyを付けます。
[PATH]
作成されたスクリプトの先頭には、以下のようなコメントがあります。
# /// script
# requires-python = ">=3.13"
# dependencies = []
# ///
これは、実行するPythonやライブラリのバージョンを指定するメタ情報です。 PEP 723で規定されています。
プロジェクトのファイル #
uv initの--appまたは--libオプションでプロジェクトを作成したときのファイルを説明します。
.python-version #
.python-versionの中身は以下のようになっています。
uvが仮想環境にインストールするPythonのバージョンを指定するファイルです。
3.13
pyproject.toml #
pyproject.tomlはPythonプロジェクトのメタ情報を定義するファイルです。
メタ情報の一例を以下に示します。
- プロジェクトの名称
- プロジェクトのバージョン
- 実行に必要なPythonのバージョン範囲
- 実行に必要なライブラリやそのバージョン範囲
仮想環境の作成 #
uv initコマンドを実行しただけでは、uvの仮想環境は作成されていません。
仮想環境を構築するには、pyproject.tomlがある階層で、以下のコマンドを実行します。
uv sync
実行すると、.venv/フォルダとuv.lockというファイルが作成されます。
.venv/には、Pythonの実行ファイルやライブラリなどがあります。
また、uv.lockはインストールするライブラリのバージョンなどを記載したファイルです。
したがって、PythonプロジェクトをGitサーバからcloneし、開発環境を再現する場合、一般的には以下の作業フローになると思います。
- GitサーバなどからPythonプロジェクトのリポジトリをcloneする。
pyproject.tomlと同じディレクトリでuv syncコマンドを実行し、仮想環境を構築する。
なお、pyproject.tomlファイルがない状態で仮想環境を作成する場合、以下のコマンドを実行します。
uv venv
実行すると、.venv/フォルダが作成されます。
スクリプトの実行 #
Pythonスクリプトを実行する方法を示します。
ここでは、uv init --app myappというコマンドでmyappというプロジェクトを作成したものとします。
プロジェクトにmain.pyというスクリプトが作成されているため、これを実行します。
仮想環境に入らない場合 #
仮想環境に入らずにスクリプトを実行する場合、uv run <script>とします。
> uv run .\main.py
Hello from myapp!
仮想環境に入る場合 #
uv runコマンドではなく、従来通りにpythonコマンドでスクリプトを実行したい場合、仮想環境に入ります。
PowerShellの場合、activate.ps1というスクリプトを実行すると、仮想環境に入ります。
仮想環境に入ると、プロンプトの左側に仮想環境の名前が表示されます。
> .\.venv\Scripts\activate.ps1
(myapp) >
仮想環境に入った状態では、pythonコマンドで仮想環境のPythonが使用できます。
> python .\main.py
Hello from myapp!
なお、Windows環境ではpy .\main.pyのようにpyコマンドでもPythonを実行できます（未確認ですが、Linuxではpyコマンドを使用できないかもしれません）。
仮想環境から抜ける場合、deactivateコマンドを実行します。
(myapp) > deactivate
>
Pythonのバージョン指定 #
uv init #
uv initで作成するプロジェクトにおいてPythonのバージョンを指定する場合、--python [VERSION]オプションを付けます。
uv init --python 3.13.7 [PATH]
指定したバージョンが.python-versionファイルに記載されます。
また、pyproject.tomlには「指定したバージョン以上でなければならない」と記載されます。
[project]
requires-python = ">=3.13.7"
なお、以下のようにパッチバージョンを省略することも可能です。
uv init --python 3.13 [PATH]
uv sync #
uv syncで作成する仮想環境においてPythonのバージョンを指定する場合、--python [VERSION]オプションを付けます。
uv sync --python 3.13.7 [PATH]
uv venv #
uv venvで作成する仮想環境において、Pythonのバージョンを指定する場合、--python [VERSION]オプションを付けます。
uv venv --python 3.13.7 [PATH]
まとめ #
uv init: Pythonのプロジェクトを作る。仮想環境は構築しないuv sync:pyproject.tomlからライブラリを含む仮想環境を構築するuv venv:pyproject.tomlがない状況で仮想環境を構築する
