uv 0.12 リリースノート（破壊的変更を含む）

2026 年 7 月 28 日リリースの uv 0.12.0。前回の 0.11.0 から蓄積した変更により、以下の項目が**「破壊的変更」**として标记されています。

多くのユーザーは追加の変更なしにアップグレード可能ですが、

uv_build

• [build-system] テーブルに

  uv_build

  の上限バージョンが含まれている場合、

  uv_build>=0.11.32,<0.13

  として0.12 を許可するように更新してください。

主要な破壊的変更

1.

uv init

でデフォルトでビルドシステムを定義

• 以前:

  uv init example

  は

  [build-system]

  なし（非パッケージ化）で作成。依存関係は宣言できず、仮想環境にインストールされなかった。
• 今: 作成時に**

  [build-system]

  を定義**（

  uv_build

  使用）。
  • アプリケーションソースコードは

    src/example

    に配置される。

  • [project.scripts]

    エントリが追加され、コマンドとして実行可能になる。
• 影響: テストや他のコードからインポート・インストールが可能になる。

  $ uv init example
  $ cd example
  $ uv run example
  Hello from example!
  

• 既存プロジェクトへの影響: ありません。非パッケージ化レイアウトを維持するには

  uv init --no-package example

  を使用してください。

2. 非対応のソース配布物およびホイールアーカイブ形式を拒否

• .tar.bz2

  /

  .tar.xz

  の廃止: PEP 625 に準拠し、

  .tar.gz

  アーカイブのみを受け入れます。
• ホイール形式の制限: bzip2/LZMA/XZ 圧縮されたエントリは拒否されます。stored / DEFLATE / zstd のみ許可されます。

• .zip

  ソース配布物: レガシー互換のため、引き続きサポートされています（ただし上記アーカイブ形式の制限には注意）。
• 対応策: 既存ロックファイルにレガシー形式が含まれている場合、

  .tar.gz

  アーカイブとして再構築し、ロックファイルを再生成してください。

3. Python インタープリターを置き換える可能性のあるホイールファイルを受け付けない

• 拒否対象:

  • Python

    （大文字小文字区別がない場合）、

    python.py

    、

    Python.exe

    など、予約されたインタプリタ名のケース不感変種。

  • .data/scripts

    や

    .data/data/bin/python

    などに配置し、エントリーポイントチェックを回避するファイル。
• 理由: macOS/Windows などで仮想環境のインタプリタを上書きするリスクがあるため。
• 対応策: 競合するエントリーポイントを改名し、影響を受けたホイールを再構築してください。

4. プレリリースにフォールバックする前に安定版リリースを優先

• 新しいデフォルトモード (

  if-necessary

  ):
  • まず**安定版（Stable）**を試み、制約を満たさなければプレリリースにフォールバックします。
  • 以前は

    if-necessary-or-explicit

    で、直接要件か明示的でない限りプレリリースを許可せず、依存関係グラフ全体でのプレリリース許可が必要でした。
• 注意: パッケージ両方の候補がある場合でも、バージョン選択が以前の uv と異なる可能性があります。
• フラグ:

  • --prerelease disallow

    : 自動的なプレリリース選択を無効化。

  • --prerelease allow

    : プレリリースを優先（安定版は除外）。

  • --prerelease explicit

    : 明示的に言及されたプレリリースのみ許可。

5.

requirements.txt

内の

--require-hashes

指令を尊重

• 以前: 警告は出てもハッシュチェックを行わずインストールしていました。
• 今: コマンドラインの

  --require-hashes

  を渡した場合と同じように、ファイル内の指令を強制します。
• 非対応例:

  # ハッシュ化されていない要件は無効化されます
  some-package>=1.0.0
  

• 対応策: 全要件を

  ==

  で固定しハッシュを提供するか、

  --require-hashes

  を削除してください。

6. ハッシュチェックモードで MD5 単体のハッシュを拒否

• 理由: MD5 は衝突に耐性がないため、ハッシュ検証が必要なセキュリティ上リスクが高い。
• 今:

  --require-hashes

  モードでは、SHA-256 など少なくとも 1 つの安全なダイジェストが必要です。MD5 単体は拒否されます。

  # SHA-256 などの安全なハッシュがないと拒否されます
  anyio==4.0.0 --hash=md5:420d85e19168705cdf0223621b18831a
  

• 対応策: SHA-256 などを使用して影響を受けるハッシュを再生成してください。

7.

pylock.toml

ファイルおよびアーティファクトの無効なものを拒否

• パッケージ配列必須: 欠落した配列は空のロックファイルとして解釈されず、エラーになります。明示的に

  packages = []

  は有効です。
• ファイル名形式:

  pylock.toml

  または単一名称バリアント（例：

  pylock.dev.toml

  ）のみ許可。

  pylock..toml

  など複合名称は拒否されます。
• サイズ整合性: アーティファクトがサイズを宣言している場合、ダウンロード済みアーティファクトと一致する必要があります。

8. 証明書が読み込めない場合でも明示的な証明書オーバライドを尊重

• 以前:

  SSL_CERT_FILE

  /

  SSL_CERT_DIR

  が無効な場合、デフォルトルートにフォールバックしました。
• 今: 非空の値（有効か無効かを問わず）は常にデフォルト証明書ルートを置き換えます。無効なパスが指定されていると HTTPS リクエストは失敗します。
• 対応策: 証明書を修正するか、環境変数を未設定に戻してください。

9.

uv pip

で pip 互換の

--cert

ハンドリングをサポート

• 新機能:

  uv pip install --cert <path>

  がサポートされました。
• 動作: 提供された PEM バンドルが他のすべての証明書ソース（システム、

  SSL_CERT_FILE

  など）を置き換えます。
• 対象:

  uv pip

  コマンドのみ。

10.

uv run

に渡されたスクリプトに対してプロジェクトを相対的に発見する

• 以前: 現在のディレクトリからプロジェクトを発見しました。
• 今: スクリプトのディレクトリからプロジェクト/ワークスペースを発見します。

  # other-project ディレクトリから検索し、その依存関係を使用します
  $ uv run other-project/script.py
  

• オプトアウト: 明示的に

  uv run --project . script.py

  を使用してください。

11. 仮想環境ではないディレクトリをクリアする前に

--force

を必要とする

• 以前:

  uv venv --clear

  は警告を出しつつも、仮想環境でなくても削除しました。
• 今: 仮想環境でないディレクトリのクリアは拒否されます。
• 対応策:

  uv venv --clear --force ./not-a-virtualenv

  のように

  --force

  を指定してください。

12. プロジェクトを初期化する際に

--project

を拒否

• エラー化:

  uv init --project example

  は即座に失敗します（新しいプロジェクト作成には不要）。
• 正しい使い方:
  • 新規作成:

    uv init example

  • パス変更:

    uv init --directory example

13. 欠落しているか無効な

--project

パスを拒否

• 以前: 警告は出しましたが、実行を試みました（後続エラーの原因）。
• 今:

  uv run --project missing python

  は即座に失敗します。
• 対応策: ディレクトリを先に作成するか、既存のプロジェクトを選択してください。

14. 公開時に正規化されていないファイル名を持つ配布物をスキップする

• 要件: ホイール/ソース配布物のファイル名は正規化されたパッケージ名・バージョンを使用する必要があります。
  • ✅

    example-1.1.0-py3-none-any.whl

    （1.1.0 へ正規化）
  • ❌

    example-1.01.0-py3-none-any.whl

    （そのまま）
• 対応策: 影響を受ける配布物をスキップし、正規化されたファイル名を持つものを再構築してください。

15. パスに基づいて

base

および

root

と命名された Conda 環境を分類する

• 変更:

  base

  や

  root

  という名前が Conda 子環境としても認識されます（以前は常に基本環境と判断）。
• オプトアウト: 明示的なインタプリタ指定（

  --python /path/to/python

  ）で回避可能。

16. 環境発見中に壊れた

.venv

シンケリンクを拒否する

• 以前: 壊れたリンクを無視し、親ディレクトリの環境を検索しました。
• 今: 壊れたリンクで即座に停止し、正確なパスを報告します。エラー（権限失敗など）も即座に報告されます。
• 対応策: 壊れた

  .venv

  リンクを修復/削除し、権限問題を修正してください。

17. 明示的にアップグレードする代わりに一致するインストールされた Python パッチバージョンを再インストールする

• 変更:

  uv python install 3.12 --reinstall

  は、最新のパッチリリースを取得せず、既存の一致するパッチバージョンを再インストールします。
  • 例:

    3.12.6

    と

    3.12.7

    があれば、両方を再インストール。
• 対応策: 最新のアップグレード動作に戻すには

  uv python install 3.12 --upgrade

  を使用してください。

18. 既存の依存関係グループを名付けるために

--upgrade-group

を必要とする

• 変更:

  uv lock --upgrade-group docs

  が、ドキュメントグループが存在しない場合でも成功するのをやめました。検証を行います。
• 対応策: グループ名を修正するか、

  [dependency-groups]

  に追加してください。

19.

--directory

に対して相対的なインデックスおよび find-links を解決する

• 以前: コマンドラインの相対パスは元の作業ディレクトリに対して解決されました。
• 今:

  --index

  /

  --find-links

  の相対パスは、

  --directory

  で指定されたディレクトリに対して解決されます。

  # プロジェクトディレクトリ内から ./packages を参照
  $ uv add --directory project --index ./packages example
  

20.

uv add

に提供された絶対パスを保存する

• 変更:

  pyproject.toml

  /

  uv.lock

  に絶対パスまたは

  file://

  URL そのまま記録されます。相対パスへの自動変換は廃止されました。

  $ uv add ../library             # 相対パスのまま
  $ uv add /projects/library      # 絶対パスのまま
  

• 推奨: ポータビリティのために相対パスを使用してください。

21. bzip2 アーカイブのみで入手可能な古い PyPy 配布物を削除する

• 対応策:

  uv python install

  では、gzip 圧縮アーカイブとしての最新 PyPy リリースのみが利用可能です。bzip2 専用リリースは除外されます。

22. 注釈が無効化されているときに除外されたパッケージのコメントを省略する

• 変更:

  uv pip compile --no-annotate

  を使用すると、除外パッケージのフッターコメントも省略されます。

アテステーションについて

このリリースのアーティファクトには、GitHub Artifact Attestations が付与されています。

• GitHub CLI を使用して検証可能。
• GitHub からアテステーションをダウンロードして直接検証も可能です。