uv 0.5.x 版本全記錄從破壞性變更到 PEP 723 腳本鎖文件的技術(shù)演進(jìn)【免費(fèi)下載鏈接】uvAn extremely fast Python package and project manager, written in Rust.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/uv/uv本文基于 uv 倉(cāng)庫(kù)中的 changelogs/0.5.x.md 展開系統(tǒng)梳理 uv 0.5.0 至 0.5.31 共 32 個(gè)版本的演進(jìn)脈絡(luò)10 項(xiàng)破壞性變更的動(dòng)機(jī)與源碼實(shí)現(xiàn)、0.5.3 引入的“沖突 extras”conflicting extras機(jī)制及 PyTorch CPU/GPU 雙索引實(shí)戰(zhàn)配置、0.5.17 落地的 PEP 723 腳本鎖文件工作流以及貫穿整個(gè)系列的錯(cuò)誤信息改進(jìn)、性能優(yōu)化與托管 Python 發(fā)行版更新。讀完后你將能夠理解每次升級(jí)需要關(guān)注的行為差異并掌握依賴沖突、Python 版本固定、腳本鎖定等高級(jí)場(chǎng)景的落地方法。0.5.x 系列定位一個(gè)“積累型”的版本線0.5.x是 uv 發(fā)展史上的一個(gè)關(guān)鍵階段。0.5.0 的發(fā)布說(shuō)明中寫道自 Python 版本管理、項(xiàng)目管理和工具管理三大能力上線以來(lái)uv 保持了快速迭代距離上一次破壞性變更已發(fā)布了三十個(gè)版本在此期間積累的大量“提升正確性與用戶體驗(yàn)但可能破壞部分工作流”的變更被集中放入 0.5.0 一并發(fā)布。官方也明確表態(tài)大多數(shù)用戶無(wú)需修改任何內(nèi)容即可升級(jí)。整條 0.5.x 線包含從 0.5.0 到 0.5.31 共 32 個(gè)版本大致可分為四個(gè)階段階段版本范圍主題破壞性變更集中發(fā)布 穩(wěn)定性打磨0.5.0 – 0.5.210 項(xiàng) Breaking Changes、--outdated系列命令、構(gòu)建失敗診斷增強(qiáng)沖突依賴與解析器深化0.5.3 – 0.5.6沖突 extras/依賴組、PubGrub 內(nèi)部重構(gòu)、sysconfig 修補(bǔ)腳本與工作流完善0.5.7 – 0.5.17構(gòu)建后端預(yù)覽特性、uv python子命令增強(qiáng)、PEP 723 腳本鎖文件持續(xù)修 Bug 與性能優(yōu)化0.5.18 – 0.5.31托管 Python/PyPy 發(fā)行版更新、uvx python、--active/--bare等0.5.010 項(xiàng)破壞性變更逐條解析0.5.0 的破壞性變更是該系列最核心的內(nèi)容每一項(xiàng)都值得結(jié)合當(dāng)前倉(cāng)庫(kù)源碼理解其落地方式。1. 用 base executable 設(shè)置虛擬環(huán)境的 Python 路徑此前 uv 在創(chuàng)建虛擬環(huán)境時(shí)會(huì)先“規(guī)范化”canonicalizePython 可執(zhí)行文件的路徑再寫入環(huán)境。這帶來(lái)兩個(gè)問(wèn)題會(huì)繞過(guò)像 Homebrew 這樣的穩(wěn)定版本目錄且與 Python 標(biāo)準(zhǔn)庫(kù)venv模塊的行為不一致。0.5.0 起uv 改用sys._base_executable路徑。在當(dāng)前倉(cāng)庫(kù)中可以直接驗(yàn)證這一實(shí)現(xiàn)虛擬環(huán)境創(chuàng)建邏輯 中的注釋明確寫道“為與標(biāo)準(zhǔn)庫(kù)保持一致依賴sys._base_executable除非使用的是 uv 托管的 Python此時(shí)對(duì)符號(hào)鏈接可執(zhí)行文件可以做得更好”。具體而言create函數(shù)會(huì)區(qū)分兩種情況// For consistency with the standard library, rely on sys._base_executable, // _unless_ were using a uv-managed Python (in which case, we can do better // for symlinked executables). let base_python if cfg!(unix) interpreter.is_standalone() { interpreter.find_base_python()? } else { interpreter.to_base_python()? };而 解釋器元數(shù)據(jù) 中獲取 base 路徑的例程同樣依賴sys._base_executable在未設(shè)置時(shí)回退到sys.executable。這一區(qū)分對(duì)符號(hào)鏈接密集的發(fā)行版Homebrew、conda 等尤其重要。2. 安裝器改用 XDG 目錄~/.local/binuv 的安裝器此前使用$CARGO_HOME或~/.cargo/bin作為目標(biāo)目錄——這與 Cargo 毫無(wú)關(guān)系一直是用戶抱怨的焦點(diǎn)。0.5.0 起安裝目標(biāo)按以下優(yōu)先級(jí)確定$XDG_BIN_HOME$XDG_DATA_HOME/../bin~/.local/bin同時(shí)$UV_INSTALL_DIR環(huán)境變量始終可以覆蓋目標(biāo)目錄。升級(jí)時(shí)需要留意的一點(diǎn)是舊版本安裝在~/.cargo/bin中的 uv 不會(huì)自動(dòng)遷移倉(cāng)庫(kù)文檔中也相應(yīng)清理了對(duì)~/.cargo/bin的殘留引用0.5.1 的文檔更新項(xiàng)。3. 向上發(fā)現(xiàn).python-version文件此前 uv 只讀取工作目錄下的.python-version文件0.5.0 起uv 會(huì)向父目錄逐級(jí)查找但不會(huì)越過(guò)項(xiàng)目邊界繼續(xù)向上搜索。這一行為與pyenv和 Rye 保持一致。當(dāng)前倉(cāng)庫(kù)的 版本文件發(fā)現(xiàn)模塊 印證了這一設(shè)計(jì)PythonVersionFile::discover從工作目錄開始向上尋找“最近”的版本文件并通過(guò)DiscoveryOptions中的stop_discovery_at字段控制搜索邊界——項(xiàng)目邊界正是通過(guò)該選項(xiàng)傳入的。值得注意的是該模塊同時(shí)支持.python-version單版本固定和.python-versions多版本聲明兩種文件名并可通過(guò)FilePreference指定優(yōu)先級(jí)。4.uv.toml中出現(xiàn)“禁止項(xiàng)”時(shí)報(bào)錯(cuò)部分設(shè)置只能定義在pyproject.toml中。舊行為是這些設(shè)置若出現(xiàn)在uv.toml里會(huì)被靜默忽略新行為是直接報(bào)錯(cuò)。這是一個(gè)典型的“寧可報(bào)錯(cuò)也不靜默”的設(shè)計(jì)決策——靜默忽略會(huì)讓用戶困惑于“為什么我配置了卻不生效”。5. 實(shí)現(xiàn)符合 PEP 440 的 local version 語(yǔ)義這是 0.5.0 中技術(shù)含量最高的一項(xiàng)變更。PEP 440 的 local version如2.0cpu語(yǔ)義在 PubGrub 求解算法中實(shí)現(xiàn)極為復(fù)雜uv 此前并不完全符合規(guī)范。0.5.0 起uv 有了規(guī)范一致的本地版本實(shí)現(xiàn)對(duì)torch2.1.0的請(qǐng)求即使不帶 local tag 的torch2.1.0并不存在也可以安裝torch2.1.0cpu。這一點(diǎn)在當(dāng)前倉(cāng)庫(kù)的 uv-pep440 版本實(shí)現(xiàn) 中可以看到完整支撐Version內(nèi)部維護(hù)獨(dú)立的local: LocalVersion字段支持Segments按分隔的段與Max表示大于任意 local 版本兩種形態(tài)并在with_local/with_local_segments等方法上提供精確的版本構(gòu)造與比較能力。6. Conda base 環(huán)境被視為系統(tǒng)環(huán)境舊行為下uv 不區(qū)分 base 與其他 Conda 環(huán)境。0.5.0 起uv 通過(guò)CONDA_DEFAULT_ENV變量以及base/default這兩個(gè)名字判斷當(dāng)前經(jīng)CONDA_PREFIX激活的是否為 base 環(huán)境若是必須使用--system標(biāo)志才能修改它。這是對(duì) Conda 用戶誤操作 base 環(huán)境這一常見事故的防護(hù)。7.!操作符不再隱式允許預(yù)發(fā)布版本此前版本約束中出現(xiàn)預(yù)發(fā)布說(shuō)明符即被視為“opt-in 允許預(yù)發(fā)布”。新行為下使用不等于操作符如! 2.0a1時(shí)不再允許預(yù)發(fā)布版本。其余變更0.5.0 還有幾項(xiàng)范圍較窄但同樣重要的破壞性變更Windows 主目錄選擇從directoriescrate 切換到etcetera后優(yōu)先使用USERPROFILE而非FOLDERID_ProfileUSERPROFILE未設(shè)置時(shí)行為不變。顏色輸出的優(yōu)先級(jí)此前FORCE_COLOR/NO_COLOR環(huán)境變量?jī)?yōu)先于--color標(biāo)志現(xiàn)在顯式提供--color時(shí)以標(biāo)志為準(zhǔn)。后續(xù) 0.5.15 又補(bǔ)充了對(duì)FORCE_COLOR的完整支持。allow-insecure-host成為全局選項(xiàng)--allow-insecure-host現(xiàn)在可用于任意命令為保持一致性[tool.uv.pip]配置段中的allow-insecure-host設(shè)置被移除統(tǒng)一收斂到[tool.uv]。uv init只為版本不同的 workspace 成員寫.python-version由于 uv 現(xiàn)在會(huì)尊重父目錄的版本文件初始化時(shí)為成員重復(fù)生成同名版本文件已無(wú)必要。0.5.0 的新功能--outdated系列與周邊增強(qiáng)0.5.0 同時(shí)帶來(lái)了一批實(shí)用性功能uv tree --outdated直接查看依賴樹中哪些包有新版可用pip list --outdated支持pip 兼容層任意 git 傳輸協(xié)議支持gitssh://、githttp://等uv cache clean進(jìn)度條armv7l 的 armv8l 別名支持 arm 32 位兼容模式直接 URL 之后緊跟分號(hào)的解析放寬以及針對(duì) URL/路徑需求中尾部;的專門報(bào)錯(cuò)這類輸入通常是復(fù)制粘貼時(shí)誤帶了 marker 分隔符。此外0.5.0 引入了實(shí)驗(yàn)性的uv 構(gòu)建后端支持構(gòu)建基礎(chǔ) source distribution0.5.0并在后續(xù)版本持續(xù)加碼——0.5.2 增加源樹 → 源碼包 → wheel 的轉(zhuǎn)換測(cè)試與自定義glob-walkdir實(shí)現(xiàn)0.5.6 重構(gòu)include/exclude并加入快速路徑0.5.7 將直接構(gòu)建接入解析器與安裝器、為uv init提供 uv 后端模板0.5.17 補(bǔ)全全部 Python 類型標(biāo)注。0.5.3沖突 extras 與依賴組——PyTorch 雙索引實(shí)戰(zhàn)0.5.3 是 0.5.x 系列中功能含金量最高的一個(gè)版本核心是解析器對(duì)“沖突可選依賴與依賴組”的支持包括按 extra 或按依賴組粒度指定依賴來(lái)源如 index 分配。典型場(chǎng)景是運(yùn)行時(shí)選擇 CPU 版還是 GPU 版 PyTorch在pyproject.toml中聲明兩個(gè)互相沖突的 extra并將它們分別指向不同索引[project] name project version 0.1.0 requires-python 3.12.0 [project.optional-dependencies] # 提供 --extra cpu 或 --extra gpu 時(shí)都包含 torch cpu [torch2.5.1] gpu [torch2.5.1] [tool.uv] # 允許 cpu 與 gpu 選擇沖突版本的 torch conflicts [[{ extra cpu }, { extra gpu }]] [tool.uv.sources] torch [ # --extra cpu 時(shí)從 CPU 專用索引拉取非 macOS 平臺(tái) { index pytorch-cpu, extra cpu, marker platform_system ! Darwin }, # --extra gpu 時(shí)從 GPU 索引拉取 { index pytorch-gpu, extra gpu }, ] [[tool.uv.index]] name pytorch-cpu url https://download.pytorch.org/whl/cpu explicit true [[tool.uv.index]] name pytorch-gpu url https://download.pytorch.org/whl/cu124 explicit true這套機(jī)制的要點(diǎn)在于conflicts聲明讓 uv 能夠生成通用解析universal resolution——uv.lock同時(shí)保留兩個(gè) extra 的解而不是強(qiáng)制在鎖定時(shí)刻二選一tool.uv.sources中的extra字段則把“索引分配”綁定到具體的 extra 上explicit true保證這兩個(gè)索引只服務(wù)于被顯式指派的包不會(huì)污染默認(rèn)解析。倉(cāng)庫(kù)中 workspace 層對(duì) conflicts 的解析入口 印證了數(shù)據(jù)來(lái)源conflicts()方法從tool.uv.conflicts讀取聲明并轉(zhuǎn)換為解析器使用的Conflicts結(jié)構(gòu)源碼注釋也說(shuō)明了其用途——“當(dāng)兩個(gè)或更多 extras 互相沖突時(shí)顯式聲明沖突可以讓 uv 生成通用解析”。0.5.3 的其他重點(diǎn)--verify-hashes默認(rèn)開啟pip 兼容層默認(rèn)執(zhí)行 hash 校驗(yàn)uv tool install --force隱含--reinstall-package namePEP 723 腳本支持 overrides 與 constraints[[tool.uv.index]]對(duì)腳本的尊重也在本版本修復(fù)中落實(shí)跨平臺(tái)啟用 Rust 實(shí)現(xiàn)的zlib-rs提升解壓性能。0.5.17PEP 723 腳本的鎖文件0.5.17 完成了一個(gè)完整的工作流閉環(huán)基于 PEP 723 內(nèi)聯(lián)元數(shù)據(jù)為腳本生成鎖文件。行為規(guī)則腳本默認(rèn)處于“未鎖定”狀態(tài)需顯式執(zhí)行uv lock --script /path/to/script.py生成鎖文件位置與腳本相鄰如script.py.lock生成后uv run --script、uv add --script、uv remove --script都會(huì)尊重并在必要時(shí)更新該鎖文件uv export --script與uv tree --script新增對(duì)腳本的支持無(wú)論腳本是否伴隨鎖文件均可工作。當(dāng)前倉(cāng)庫(kù)源碼中可以直接找到這一約定腳本鎖目標(biāo)定位邏輯 中的注釋明確以script.py.lock作為鎖文件命名規(guī)則集成測(cè)試 build/audit.rs 也反復(fù)用context.temp_dir.child(script.py.lock)驗(yàn)證鎖文件的創(chuàng)建與--frozen下的缺失報(bào)錯(cuò)“Unable to find lockfile atscript.py.lock”。貫穿 0.5.x 的三條主線錯(cuò)誤信息工程化整個(gè)系列中占比最高的類別是錯(cuò)誤與診斷改進(jìn)其方向高度一致把“報(bào)錯(cuò)”變成“可操作的診斷”。代表性節(jié)點(diǎn)包括0.5.2構(gòu)建失敗展示完整推導(dǎo)鏈full derivation chain早期構(gòu)建失敗與安裝失敗使用 rich 診斷格式0.5.3推導(dǎo)鏈中加入 extra、依賴組與版本約束git缺失時(shí)給出專門提示0.5.4空 stdin 的專門警告0.5.10大幅精簡(jiǎn) PubGrub 求解器錯(cuò)誤中的冗余版本枚舉--no-binary/--no-build失敗時(shí)給出針對(duì)性提示0.5.19解析器錯(cuò)誤中展示期望與實(shí)際可用的 ABI tag0.5.8git前綴缺失時(shí)的專門提示。這些改進(jìn)大多對(duì)應(yīng)crates/uv-resolver與crates/uv/src/commands下的錯(cuò)誤渲染路徑值得在遇到疑難解析失敗時(shí)對(duì)照查閱。托管 Python 發(fā)行版更新多個(gè)版本攜帶托管 Python 的批量更新對(duì)使用uv python install的用戶尤為關(guān)鍵版本更新內(nèi)容0.5.7新增 CPython3.9.21、3.10.16、3.11.11、3.12.8、3.13.10.5.15Python 3.14.0a3macOS/Linux、SQLite 特性檢測(cè)修復(fù)0.5.19Python 3.14Windows、3.14.0a4、64 位 RISC-V Linux 支持0.5.29CPython 3.12.9、3.13.2pkg-config 文件可重定位0.5.30PyPy v7.3.18PyPy3.10 / PyPy3.11 beta0.5.31CPython 3.14.0a5含尾調(diào)用解釋器、OpenSSL 3.0.15 → 3.0.16 安全更新配套能力也在同步演進(jìn)0.5.2 允許在uv.toml配置 Python/PyPy 下載鏡像0.5.8 新增--install-dir、--show-urls、--only-downloads、--all-arches等uv python選項(xiàng)0.5.6 起預(yù)覽特性支持uv python install --default。性能與內(nèi)部重構(gòu)性能優(yōu)化條目數(shù)量龐大反映出 0.5.x 期間對(duì)解析器熱路徑的持續(xù)雕琢數(shù)據(jù)結(jié)構(gòu)瘦身Dist從 352 字節(jié)縮到 288 字節(jié)0.5.16進(jìn)一步降到 200 字節(jié)0.5.19WheelFilename縮至 48 字節(jié)內(nèi)存與分配包名/extra/group 名改用ArcStrPEP 508 解析器免分配0.5.17標(biāo)記值免String克隆0.5.6求解器遷移到 PubGrub arena 管理包名0.5.5、0.5.17 將非 first-match 索引策略的抓取并發(fā)化、0.5.22 起通過(guò) GitHub API 快速路徑直接取pyproject.toml并配套校驗(yàn)與非致命回退、0.5.27 升級(jí) PubGrub 的集基過(guò)時(shí)優(yōu)先級(jí)跟蹤內(nèi)存分配器0.5.14 讓 jemalloc 真正作為替代分配器生效0.5.16 全平臺(tái)重新啟用zlib-ngs390x/PowerPC/FreeBSD 除外。后續(xù)版本速覽0.5.21 – 0.5.310.5.21新增UV_VENV_SEED環(huán)境變量控制是否向新建虛擬環(huán)境預(yù)裝setuptools/pip等種子包0.5.23uv venv --refresh、--no-default-groups命令行標(biāo)志0.5.25首次發(fā)布Windows aarch64二進(jìn)制發(fā)布簽名采用 GitHub attestations0.5.27 完善0.5.26uvx python支持——可直接以工具方式運(yùn)行任意版本 Python0.5.29uv init --bare僅生成最小pyproject.toml--active讓項(xiàng)目命令尊重已激活的VIRTUAL_ENV--no-active可靜默相關(guān)警告0.5.30uv sync --dry-runNO_BINARY/NO_BINARY_PACKAGE環(huán)境變量0.5.31uv sync --script補(bǔ)全腳本工作流工具請(qǐng)求支持完整 PEP 508 語(yǔ)法uv run獲得無(wú)限遞歸檢測(cè)。升級(jí)指引結(jié)合 0.5.x 的整體走向升級(jí)時(shí)的檢查清單確認(rèn) uv 安裝位置若仍在使用~/.cargo/bin中的舊安裝0.5.0 起安裝器默認(rèn)指向~/.local/binXDG 目錄必要時(shí)用UV_INSTALL_DIR顯式指定檢查uv.toml其中若存在僅允許出現(xiàn)在pyproject.toml的設(shè)置新版會(huì)直接報(bào)錯(cuò)0.5.0[tool.uv.pip]下的allow-insecure-host需遷移到[tool.uv]符號(hào)鏈接密集的 Python 安裝Homebrew、conda base虛擬環(huán)境內(nèi)的解釋器路徑解析行為已變化Conda base 環(huán)境現(xiàn)在需要--system才能修改依賴預(yù)發(fā)布的聲明依賴! x.yaN形式的“隱式預(yù)發(fā)布 opt-in”的解析結(jié)果可能變化local version 依賴如依賴2.0cpu這類 local 版本0.5.0 起規(guī)范語(yǔ)義下解析結(jié)果可能與舊版不同更正確但結(jié)果可能變化。除上述各點(diǎn)外官方預(yù)期大多數(shù)工作流無(wú)需改動(dòng)即可平滑升級(jí)。更細(xì)粒度的逐版本條目可查閱 changelogs/0.5.x.md 原文與 changelogs/0.4.x.md、changelogs/0.6.x.md 銜接閱讀可還原 0.4 → 0.6 的完整演進(jìn)本文涉及的源碼證據(jù)集中在 crates/uv-virtualenv/src/virtualenv.rs、crates/uv-python/src/version_files.rs、crates/uv-pep440/src/version.rs、crates/uv-workspace/src/pyproject.rs 與 crates/uv/src/commands/project/lock_target.rs可按圖索驥進(jìn)一步深入?！久赓M(fèi)下載鏈接】uvAn extremely fast Python package and project manager, written in Rust.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/uv/uv創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考