Zenn
🌅

初めてのuv入門｜uvコマンドガイド：Utilities編

に公開
Python
uv
tech

知識は武器とかけまして、レゴブロックと解く、その心は――
今日もKnowledge Oasisへようこそ
案内人はkoふみです
本日のテーマは『uv コマンドガイド Utilities編』

はじめに

Pythonプロジェクトの開発では、パッケージ取得の高速化や環境の再現性を保つために、キャッシュやツール自身のバージョン管理が欠かせません。uvは依存キャッシュの操作から、uvコマンド自身のアップデート、さらにはシェル補完の生成まで、開発のオアシスのように一手で整えてくれる頼もしい相棒です。本記事では、uv cache clean／uv cache prune／uv cache dir などキャッシュ操作コマンドと、uv self update／uv self version／uv generate-shell-completion の各コマンドについて、概要から使い方、オプション、ポイントまで丁寧に解説します。

対象読者

  • プロジェクトの依存キャッシュを手動で管理したいエンジニア
  • uv自身をオンデマンドでアップデート／バージョン確認したい方
  • シェル補完スクリプトを手軽に生成し、自動化したい方

コマンド解説

uv cache clean: キャッシュを完全に消去する

概要

uv cache clean は、uvが保持する全キャッシュを削除するか、あるいは指定パッケージに紐づくキャッシュだけを消去するコマンドです。既存のキャッシュが原因で不具合が起きたときのリセットに役立ちます。

使い方

# 全エントリを削除
$ uv cache clean

# 特定パッケージのキャッシュのみ削除
$ uv cache clean ruff

主なオプション

  • PACKAGE：削除対象のパッケージ名を指定（省略時は全消去）。
  • --cache-dir <ディレクトリ>：キャッシュディレクトリを明示的に指定。

ポイント

  • 開発中に依存のバイナリが壊れた際は、まずこのコマンドで全消去してから再度インストールを試しましょう。
  • CI環境などで一時的にキャッシュを無効化したい場合は、--no-cacheオプションと組み合わせると便利です。

uv cache prune: 使われていないキャッシュを削除する

概要

uv cache prune は、不要になったキャッシュオブジェクトだけを洗い出して削除するコマンドです。バージョンアップや古い依存が残ったままになっている場合に、ディスク容量を効率的に開放できます。

使い方

# 未使用キャッシュのクリーンアップ
$ uv cache prune

# CI向け最適化（ビルド済みホイールのみ残す）
$ uv cache prune --ci

主なオプション

  • --ci：CI環境用に、ビルド済みホイールは残しつつ不要ファイルを削除。
  • --cache-dir <ディレクトリ>：キャッシュディレクトリを明示的に指定。

ポイント

  • 定期的に実行すると、キャッシュディレクトリが肥大化するのを防げます。
  • GitHub Actionsなどのパイプライン末尾で --ci を指定しておくと、次回の再取得が最速になります。

uv cache dir: キャッシュ保存先を表示する

概要

uv cache dir は、現在uvが利用しているキャッシュディレクトリのパスを出力するコマンドです。ディスク使用状況の確認や、手動バックアップの際に活用します。

使い方

$ uv cache dir
# 例: /home/user/.cache/uv

主なオプション

  • --cache-dir <ディレクトリ>：表示対象のキャッシュディレクトリを上書き指定。
  • --allow-insecure-host：信頼できないホスト経由のキャッシュ操作を許可（特殊用途）。

ポイント

  • デフォルトでは $XDG_CACHE_HOME/uv（Unix系）や %LOCALAPPDATA%\uv\cache（Windows）を参照します。
  • 高速化のため、キャッシュディレクトリはPython環境と同じファイルシステムに置くのがおすすめです。

uv self update: uvを最新版に更新する

概要

uv self update は、現在インストールされているuvを最新バージョン（または指定バージョン）へアップデートするコマンドです。インストーラーを再実行してバイナリを更新します。

使い方

# 最新版へ更新
$ uv self update

# 特定バージョンへ更新
$ uv self update 0.7.10

主なオプション

  • TARGET_VERSION：更新先のバージョンを指定（省略時は最新）。
  • --dry-run：実際の更新を行わずにシミュレーションのみ。
  • --allow-insecure-host：信頼できないホスト経由のダウンロードを許可。

ポイント

  • 他の方法（pipやHomebrew）でインストールした場合は、このコマンドは無効です。その場合は各パッケージマネージャで更新してください。

uv self version: uvのバージョンを表示する

概要

uv self version は、現在利用中のuvのバージョン情報を表示するコマンドです 。

使い方

$ uv self version

主なオプション

  • --short：バージョン番号のみを出力。

ポイント

  • 問題報告やトラブルシューティングでは詳細版を、スクリプト内取得やCIパイプラインでは--shortを併用すると便利です。

uv generate-shell-completion: シェル補完スクリプトを生成する

概要

uv generate-shell-completion は、Bash／Zsh／Fish／Elvish／PowerShell 向けの補完スクリプトを生成するコマンドです。シェル設定ファイルに組み込んでおくことで、uvコマンド入力が自動補完されるようになります 。

使い方

# bash用スクリプトを生成
$ uv generate-shell-completion bash

# zsh用スクリプトを生成
$ uv generate-shell-completion zsh

主なオプション

  • SHELL：生成対象のシェル名（bash, zsh, fish, elvish, powershell）。
  • --directory <ディレクトリ>：出力先ディレクトリを指定。
  • --managed-python／--no-managed-python：uv管理のPythonを使うか否かを制御。

ポイント

  • 生成したスクリプトは、例として echo 'eval "$(uv generate-shell-completion bash)"' >> ~/.bashrc のように追記しておくと便利です。
  • uvx でも同じ補完を使いたい場合は、uvx --generate-shell-completion <shell> を活用できます。

まとめ

本記事では、uvのキャッシュ操作から自己更新、シェル補完生成までを６つのコマンドに絞って解説しました。依存キャッシュをクリーンに保ち、uv自身を最新に保つことで、開発のオアシスがよりクリアに、より快適になります。ぜひこれらのコマンドを日々のワークフローに取り入れてみてください。

知識のひとつひとつは小さなレゴブロック
でも、組み合わせれば世界を変えるアイディアをカタチにする武器になる！

またKnowledge Oasisでお会いしましょう
案内人はkoふみでした

Discussion