Windows向け uv環境構築 実践メモ: uvの導入やプロジェクト作成をbatファイルにする方法

この記事では、uv の導入やプロジェクト作成を bat ファイルで少し楽にする方法をまとめます。

• install_uv.bat の作り方
• uv_init_project.bat の作り方
• uv_sync.bat の作り方
• uv_update.bat の作り方
• 1本にまとめず分ける理由
• エンコードで困らないための注意点

記事一覧: Windows向け uv環境構築 実践メモ: 記事一覧

先に結論

bat ファイルにすると、毎回同じコマンドを打たなくてよくなります。
ただし、Windows の bat ファイルは文字コードでつまずきやすいです。

そのため、最初に結論を書くと次の方針が無難です。

1. install_uv.bat と uv_init_project.bat は分ける
2. 既存プロジェクト用に uv_sync.bat も用意すると便利
3. アップデート用に uv_update.bat も用意すると便利
4. bat ファイル内のメッセージは、できれば英数字だけにする
5. 日本語を入れるなら、文字コードに注意する

なぜ bat ファイルを作るのか

毎回同じコマンドを打つのが面倒なとき、bat ファイルにしておくと作業を減らせます。

たとえば、こんな場面です。

• 新しいPCで同じ初期設定をしたい
• 社内やチームで手順をそろえたい
• 自分用の忘備録として残したい

特に初心者のうちは、「どの順番で打つんだっけ？」となりやすいので、手順をファイルにしておく価値があります。

なぜ役割別に分けるのか

ここは1本に全部詰め込むより、役割ごとに分けた方が分かりやすいです。

• install_uv.bat: uv をインストールする
• uv_init_project.bat: プロジェクトを初期化する
• uv_sync.bat: 既存プロジェクトの環境をそろえる
• uv_update.bat: uv 自体と Python をアップデートする

分けた方がよい理由

uv のインストール直後は、PATH の更新が現在のターミナルに反映されないことがあります。
そのため、インストール直後にそのまま次の uv コマンドを続けると、うまく動かないことがあります。

「導入」と「導入後の利用」を分けた方が、トラブル時も切り分けやすいです。

install_uv.bat の例

まずは uv を入れるためのバッチです。

@echo off
setlocal

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

echo Install finished.
echo Reopen terminal and run: uv --version
pause

このバッチでやっていること

• 公式の PowerShell インストーラーを呼び出す
• インストール後はターミナルを開き直すように案内する

補足

bat ファイル自体はコマンドプロンプト用ですが、この中で powershellコマンドを呼び出せます。
一方で、インストール後の uv --version や uv init、uv sync などの uv コマンドは、PowerShell とコマンドプロンプトのどちらでも同じです。

uv_init_project.bat の例

次は、プロジェクトを初期化するためのバッチです。

事前にプロジェクト用のフォルダを手動で作成し、そのフォルダでプロンプトを開いてから実行してください。

@echo off
setlocal

uv python install 3.12
uv init
uv python pin 3.12
uv sync

echo Project initialized: %CD%
echo Run: uv run python --version
pause

このバッチでやっていること

• uv python install 3.12: 使うPythonを用意する
• uv init: カレントフォルダにプロジェクトのひな形を作る
• uv python pin 3.12: そのプロジェクトで使うPythonを固定する
• uv sync: 仮想環境と uv.lock を作る

使い方

1. プロジェクト用のフォルダを手動で作成する（例: C:\projects\sample-app）
2. そのフォルダでプロンプトを開く（またはコマンドプロンプトで cd して移動する）
3. uv_init_project.bat を実行する

uv_sync.bat の例

これは、すでに pyproject.toml があるプロジェクト用です。
他のPCから持ってきたプロジェクトや、チームメンバーから受け取ったプロジェクトで使いやすいです。

@echo off
setlocal

if not exist pyproject.toml (
    echo pyproject.toml not found.
    exit /b 1
)

uv sync

echo Sync finished: %CD%
echo Run: uv run python --version
pause

このバッチでやっていること

• pyproject.toml があるか確認する
• uv sync で環境をそろえる
• 実行確認の案内を出す

どんなときに使うのか

• Git で clone してきたプロジェクトを動かすとき
• 別PCへ移したプロジェクトを再セットアップするとき
• pyproject.toml と uv.lock がある既存案件を再現したいとき

uv_init_project.bat との違い

• 新しいプロジェクトを作るなら uv_init_project.bat
• 既存のプロジェクトを再現するなら uv_sync.bat

uv_update.bat の例

uv 自体と、uv が管理している Python をまとめて更新するバッチです。
セキュリティ修正などで更新が必要になったときに使いやすいです。

プロジェクトフォルダである必要はありません。どこで実行しても構いません。

@echo off
setlocal

uv self update
uv python install 3.12 --upgrade

echo Update finished.
echo Run: uv --version
echo Run: uv python list
pause

このバッチでやっていること

• uv self update: uv 自体を最新版へ更新する
• uv python install 3.12 --upgrade: Python 3.12 系を最新 patch 版へ更新する

使い方

1. uv_update.bat をダブルクリック、またはプロンプトから実行する
2. 完了後、uv --version と uv python list でバージョンを確認する

注意点

• uv self update が使えるのは standalone installer で入れた場合です
• 3.12 の部分は、使っているバージョンに合わせて変更してください
• 更新後は、プロジェクトフォルダで uv sync を実行しておくと安心です

なぜサンプルのメッセージを英数字だけにしているのか

bat ファイルは、文字コードによって日本語が文字化けしやすいです。
そのため、まずは英数字だけのメッセージにしておくと、エンコードのトラブルを減らせます。

もちろん、日本語の echo やコメントを書いてもよいです。
ただし、その場合は保存時のエンコードに気をつける必要があります。

batファイル作成時の注意点: エンコード

ここはかなり大事です。

Windows の bat ファイルは、保存した文字コードと cmd.exe 側の扱いがずれると、日本語が文字化けすることがあります。
特に日本語のコメントや echo を入れたときに起きやすいです。

まず一番安全な考え方

• 日本語を入れないなら、英数字だけで書く
• 日本語を入れるなら、Shift_JIS 系で保存する

日本語 Windows では、bat ファイルは Shift_JIS 系で保存しておく方が無難です。
逆に、UTF-8 で保存すると環境によっては文字化けすることがあります。

VS Codeで作る場合

VS Code で bat ファイルを作るときは、次を意識すると安全です。

1. ファイル名を install_uv.bat や uv_init_project.bat にする
2. 改行コードは CRLF にする
3. 日本語を入れるなら、Shift JIS で保存する

具体的な保存方法

1. 右下の文字コード表示をクリックする
2. Save with Encoding を選ぶ
3. Shift JIS を選ぶ

すでに UTF-8 で作っていて文字化けが気になる場合は、必要に応じていったん開き直してから保存し直した方が安全です。

VS Codeでの実務的なおすすめ

• 日本語を使わない bat なら、そのままでも進めやすい
• 日本語コメントや日本語 echo を入れるなら Shift JIS
• 改行コードは CRLF

メモ帳で作る場合

メモ帳でも bat ファイルは作れます。

保存時のポイント

1. ファイル名を install_uv.bat のようにする
2. ファイルの種類 は すべてのファイル にする
3. 日本語を入れるなら、文字コードは ANSI を選ぶ

日本語 Windows のメモ帳でいう ANSI は、実質的に Shift_JIS 系として扱われることが多いです。
そのため、bat ファイルで日本語を使うなら、まずは ANSI 保存が無難です。

メモ帳での注意

• UTF-8 で保存した bat は、環境によって文字化けすることがある
• 拡張子が .txt にならないように注意する
• 不安なら、英数字だけの bat にしておくと安全

文字化けを避けたいなら

初心者向けには、次の順番で考えるのがおすすめです。

1. まずは英数字だけの bat を作る
2. 動作が確認できたら、日本語メッセージが必要か考える
3. 日本語を入れるなら Shift JIS か ANSI で保存する

この順番なら、コマンドの問題なのか、エンコードの問題なのかを切り分けやすいです。

batファイルの使い分けをまとめると次のとおりです。

batファイル	使う場面	主な処理
install_uv.bat	初回セットアップ（uv 本体の導入）	PowerShell インストーラー呼び出し
uv_init_project.bat	新規プロジェクトを作るとき	uv init + uv sync
uv_sync.bat	pyproject.toml がすでにあるとき	uv sync のみ
uv_update.bat	uv や Python を更新したいとき	uv self update + uv python install --upgrade

まとめ

今回のポイントは次のとおりです。

• bat ファイルにすると、繰り返し作業を減らせる
• install_uv.bat・uv_init_project.bat・uv_sync.bat・uv_update.bat と役割別に分けると整理しやすい
• uv コマンド自体は PowerShell と cmd で同じ
• 日本語入りの bat はエンコードで文字化けしやすい
• VS Code なら Shift JIS と CRLF、メモ帳なら ANSI を意識すると安全

最初は少し面倒に見えますが、一度作っておくと、次からかなり楽になります。

参考

• uv公式トップ: https://docs.astral.sh/uv/
• Installation: https://docs.astral.sh/uv/getting-started/installation/

補足

この記事は生成AIを活用して作成しました。