uv 簡單介紹

2025-03-09
3 min read
Programming
Software note
Featured Image

uv 是一個很方便的 Python 管理工具。這裡是一個簡單的介紹，詳細說明請看uv 的說明文件。

Install uv

依官方的步驟來安裝 Installation | uv。

管理 Python 版本

列出可安裝的 Python 版本

用 uv python list 可以列出可安裝的 Python 版本。 如果你已經有安裝某個版本了，<download available> 會變成你的安裝路徑。

❯ uv python list
cpython-3.14.0a5+freethreaded-windows-x86_64-none    <download available>
cpython-3.14.0a5-windows-x86_64-none                 <download available>
cpython-3.13.2+freethreaded-windows-x86_64-none      <download available>
cpython-3.13.2-windows-x86_64-none                   <download available>
cpython-3.12.9-windows-x86_64-none                   <download available>
cpython-3.11.11-windows-x86_64-none                  <download available>
cpython-3.10.16-windows-x86_64-none                  <download available>
cpython-3.9.21-windows-x86_64-none                   <download available>
cpython-3.8.20-windows-x86_64-none                   <download available>
cpython-3.7.9-windows-x86_64-none                    <download available>
pypy-3.11.11-windows-x86_64-none                     <download available>
pypy-3.10.16-windows-x86_64-none                     <download available>
pypy-3.9.19-windows-x86_64-none                      <download available>
pypy-3.8.16-windows-x86_64-none                      <download available>
pypy-3.7.13-windows-x86_64-none                      <download available>

安裝 Python

使用 uv python install <python_version> 可以安裝指定的版本，例：

uv python install 3.9 3.11 3.13

這樣就會安裝 3.9、3.11、3.13 這三個版本。

如果 uv python install 沒有指定版本的話，就會安裝目前能下載的最新版本。

移除 Python

用 uv python uninstall <python_version> 來移除一個或多個 Python 版本，<python_version> 一定要給。

Python 安裝路徑

uv python dir 會列出目前已安裝的 Python 路徑。

專案管理

單一檔案的專案

先從簡單的開始，如果你寫了有一個檔案，可以用 uv 來管理它，當你把它 copy 給人的時候，只要用 uv run <your_file.py> ，uv 就可以幫你完成相依套件的安裝，讓檔案可以順利執行。

先從建立檔案開始，例：

uv init --python 3.11 --script hello.py

這邊我們讓 uv 幫我們建立 hello.py 這個檔案，使用的環境是 Python 3.11。如果你沒有安裝 Python 3.11 ，那麼 uv 會自動幫你安裝，很方便吧。

hello.py 的內容：

# /// script
# requires-python = ">=3.11"
# dependencies = []
# ///


def main() -> None:
    print("Hello from hello.py!")


if __name__ == "__main__":
    main()

前4行就是給 uv 看的 metadata，uv 靠它來維護執行環境與套件。

安裝套件

使用 uv add 來安裝套件，假設我們需要使用 rich 這個套件：

> uv add rich --script hello.py
Updated `hello.py`

hello.py 的內容會變成：

# /// script
# requires-python = ">=3.11"
# dependencies = [
#     "rich",
# ]
# ///


def main() -> None:
    print("Hello from hello.py!")


if __name__ == "__main__":
    main()

可以看到 dependencies 增加了 rich 套件。之後你將 hello.py 傳給別人，那人只需要用 uv run hello.py，uv 就會自動安裝需要的 Python 版本與相依套件。

移除套件

用 uv remove 可以移除套件，例如 uv remove rich --script hello.py。uv 就會將 rich 從 metadata 移除。

資料夾的專案

實務上單一檔案還是不方便，uv 管理資料夾是用 uv init，例：

uv init hello_uv --python 3.13

uv 會建立 hello_uv 資料夾，Python 版本是 3.13。 資料夾的內容會有：

.git
.gitignore
.python-version
main.py
pyproject.toml
README.md
  • .git, .gitignore: uv 會自動建立 git repo，但是還沒 commit。
  • .python-version: 這個專案使用的 Python 版本，如果你在 uv init 的時候沒有指定 Python 版本，那麼就會用已安裝的最高版本。
  • main.py: 你的程式
  • pyproject.toml: pyproject.toml是 PEP 518 與 PEP 621 中提出的標準，用來定義 Python 的執行環境的設定檔

執行檔案

一樣用 uv run 就可以執行，例：uv run main.py。

在 uv run 執行過後，會多出一個 uv.lock 的檔案，這個檔案由 uv 管理（uv add會用到），uv.lock 基本上就是 pyproject.toml 的內容，uv 根據這個檔案來管理執行環境與套件。

安裝套件

在 uv 管理的資料夾內安裝套件有2個方式，uv pip install 與 uv add。

uv add

例如我們用 uv add 安裝 rich 這個套件：

uv add rich

uv 會幫你修改 pyproject.toml 與 uv.lock。

pyproject.toml 的內容會變成：

[project]
name = "hello-uv"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.13"
dependencies = [
    "rich>=13.9.4",
]

dependencies 會多出 rich 套件以及版號。

而 uv.lock 也會同步修改，內容如下：

version = 1
revision = 1
requires-python = ">=3.13"

[[package]]
name = "hello-uv"
version = "0.1.0"
source = { virtual = "." }
dependencies = [
    { name = "rich" },
]

[package.metadata]
requires-dist = [{ name = "rich", specifier = ">=13.9.4" }]

// 略

[[package]]
name = "rich"
version = "13.9.4"
source = { registry = "https://pypi.org/simple" }
dependencies = [
    { name = "markdown-it-py" },
    { name = "pygments" },
]
// 略

這樣屆時你將資料夾分享出去，只要用 uv run 就可以了，uv 會自動安裝相應的環境與套件，很方便。

uv pip

uv pip 就很單純，它就是幫你裝套件而已，在 pyproject.toml 與 uv.lock 內都不會有紀錄。

移除套件

使用 uv add 安裝的套件就用 uv remove 來移除。

使用 uv pip install 安裝的套件就用 uv pip uninstall 來移除。

pyproject.toml 被修改了怎麼辦？

先執行 uv lock 來將 pyproject.toml 的內容更新到 uv.lock ，再執行 uv sync 來更新環境與套件。

方便的 uv tool

安裝工具

之前安裝的套件都是給某個檔案或是資料夾使用，但是 Python 世界裡有些套件是可以單獨使用的，像是 yt-dlp 可以在命令列當作一個工具來用：

yt-dlp https://www.youtube.com/watch?v=111

這時候就可以用 uv tool install yt-dlp ，uv 會建立一個環境專供 yt-dlp ，不用怕污染到其他專案。 安裝好之後，yt-dlp 就可以直接使用了。

移除工具

uv tool uninstall <package_name> 可以移除工具（套件）。

更新工具

uv tool upgrade <package_name> 可以更新工具（套件）。

工具安裝位置

uv tool dir 會列出工具安裝路徑。

用 uv 執行 .py

這邊的.py 檔是指沒有被 uv 管理的檔案，假設你拿到一個檔案 test.py，你可以用 uv 來指定 Python 版本與套件來執行它。 先從最簡單的開始，例：

uv run test.py

uv 會找一個 Python 版本來執行它。uv 挑選 Python 版本的規則是這樣：

  1. 如果目前目錄有 .python-version，而且裡面有版號，那就用這一版來執行。
  2. 目前已經有啟用了某個虛擬環境，那就用這個虛擬環境來執行。
  3. 目前的目錄有 .venv 這個資料夾，那就用.venv 這個資料夾裡面紀錄的版號來執行。
  4. uv 已安裝的最高版本。
  5. 目前環境有能找到的第一個 Python 執行檔。

當然你也可以指定一個 Python 版本來執行：

uv run --python 3.11 test.py

如果指定的版本沒有安裝，uv 會自動安裝。

如果檔案裡面有需要安裝的套件，也可以寫出需要的套件，使用 --with 參數：

uv run --python 3.11 --with rich test.py

uv 會建立一個臨時的虛擬環境，幫你安裝 rich 套件，並執行 test.py。

管理臨時的虛擬環境

用 uv cache dir 列出臨時的虛擬環境的路徑。

用 uv cache clean 清除臨時的虛擬環境。

#python #uv
Avatar

Awin Huang

 有物混成，先天地而生，寂兮寥兮，獨立而不改，周行而不殆，可以為天下母。吾不知其名，字之曰道。
Next LXC 安裝 Windows 11，並分享 i915 內顯
comments powered by Disqus

Series of Posts

uv 簡單介紹
解決 Qt 線上安裝很慢的問題
TEX語法小記