Zenn
🌅

バグ修正から学ぶ：WSLでuvのhardlink警告を解消する方法

に公開
WSL
uv
hardlink
tech

知識は武器とかけまして、レゴブロックと解く、その心は――
今日もKnowledge Oasisへようこそ
案内人はkoふみです
本日のテーマは『バグ修正から学ぶ：WSLでuvのhardlink警告を解消する方法』

はじめに

「uv addを走らせたら、思わぬワーニングが出た…」そんな経験、ありませんか？
WSLの/mnt/c/Users配下でuv addを実行すると、

warning: Failed to hardlink files; falling back to full copy. This may lead to degraded performance.
         If the cache and target directories are on different filesystems, hardlinking may not be supported.
         If this is intentional, set `export UV_LINK_MODE=copy` or use `--link-mode=copy` to suppress this warning.

というメッセージが表示されます。実際にはパッケージはインストールされているものの、「hardlinkできなかった」という背後の事情を理解しないまま作業を続けると、思わぬパフォーマンス低下や管理の手間につながるかもしれません。

対象読者

  • WSL上でPython／uv（Astral UV）を使い依存関係を管理しているあなた
  • 「failed to hardlink…」の意味や対策を知りたいあなた
  • WSLのファイルシステムの違いに興味があるあなた

発生したワーニング

WSLのLinux側（ext4）とWindows側（NTFS/DrvFS）は別々のファイルシステムです。uv addはデフォルトでグローバルキャッシュ（~/.cache/uv）からファイルをハードリンクで展開しようとしますが、キャッシュとプロジェクトの置き場所が異なるファイルシステムにあると、ハードリンクが作れず自動的に「フルコピー」に切り替わり、その際に今回のワーニングが出力されます。

uvでのフルコピーの弊害

グローバルキャッシュからファイルをハードリンクや COW で参照する代わりにファイル内容を丸ごとコピーするため、インストールや同期処理のパフォーマンス低下やディスク使用量の増加が発生します。また、Docker/CI 環境ではビルド時間やイメージサイズの肥大化、ファイル I/O の増加によるボトルネックなども招きやすく、uv の高速性・効率性を大幅に損ねる可能性があります。
ワーニングだからと放置すると uv のメリットが全く活かされなくなります。

ハードリンクとは？

ハードリンクは、ファイルシステム上のデータ（inode）に対して複数のディレクトリエントリ（ファイル名）を与える仕組みです。コピーを作らず同じデータを複数の名前で参照できるため、ディスク容量を節約しつつ高速にファイルを共有できます。ただし同一ファイルシステム内でしか作成できない制約があります。

uvがハードリンクを作る理由

依存関係の展開を効率化し、ディスク操作を最小限に抑えることで、インストール処理を速く終わらせるためです。

WSLの ~/ と /mnt/c/Users の違い

WSLのホームディレクトリ（~）はディストリビューション内のLinuxファイルシステム（通常はext4）を指し、ここでのファイル操作はLinuxネイティブの性能と権限管理がそのまま使えます。一方、/mnt/c/Users はWindowsのNTFSボリュームをマウントした場所なので、どうしても遅延が大きく、パーミッションや大文字小文字の扱いもWindows準拠になります。

開発場所のベストプラクティス

WSL上でソースコードを扱うなら、~/project のようにLinux側ファイルシステム内に置くのが断然おすすめです。ファイルI/Oが速く、シンボリックリンクやUNIX権限まわりのトラブルが減ります。もしWindowsアプリ側で直接ファイルを扱う必要がある場合のみ、/mnt/c/... にファイルを配置するとよいでしょう。

ワーニングの対処

最も簡単な対処法はプロジェクトをWSLのLinuxファイルシステム（例: ~/project）に移すことです。キャッシュも同じLinux側上にあるため、uv addはハードリンクを問題なく作成できます。
また、すでにハードリンクできない状態で依存関係を追加してしまった場合は、まず uv remove パッケージ名 で一度不要なものを削除しましょう。そのうえで再びLinux側のディレクトリで uv add パッケージ名 を実行すれば、正しくハードリンクが張られます。

今回の件で学んだこと

ハードリンク

同一ファイルシステム内でのみ有効な「inodeへの別名」という仕組み。

WSLのディレクトリの違い

Linux側（ext4）とWindows側（NTFS/DrvFS）は根本的に別物。性能や権限挙動が大きく異なるので、開発用途ではLinux側を優先する。

まとめ

WSLでの開発は、できる限りホームディレクトリ（~/）配下にプロジェクトを置いて行いましょう。そうするだけでハードリンクが正しく機能し、uvのワーニングも消え、作業がスムーズになります。最初はちょっとした設定ミスかもしれませんが、この違いを押さえておくとトラブルがグッと減りますよ。

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

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

Discussion