小狐狸事務所: Python 學習筆記 : 整合型 Python 版本管理工具 uv

2026年1月24日星期六

Python 學習筆記 : 整合型 Python 版本管理工具 uv

上周胡嘉璽老師的 vibe coding 課堂介紹了uv, 這是比 venv + pip 更好用的新一代整合型 Python 套件與專案管理工具, 使用 Rust 開發故執行速度快. 因為後續 Gemini CLI 與 Claude Code 的學習測試會用到, 所以今天得空來安裝看看.

uv 的主要功能如下：

可輕鬆且快速地安裝不同的 Python 版本, 並能在這些版本之間進行切換.
可建立和管理虛擬環境, 以利在不同的專案中使用不同的 Python 版本和套件依賴.
簡單直觀的命令行介面方便執行版本管理和虛擬環境操作.
可在 Windows, macOS 和 Linux 等系統上跨平台運行.
可在 CI/CD 環境中與其他工具搭配支援自動化工作流程.

參考官網與 GitHub 說明 :

# https://docs.astral.sh/uv/

# https://github.com/astral-sh/uv

網路教學文章參考 :

# 使用 uv 管理 Python 環境

# Day 7: 從 uv 開始一個專案

1. 安裝 uv :

在 Windows 安裝 uv 的第一個方法是開啟 Power Shell 視窗, 輸入下列指令安裝 :

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

如果已經安裝過軟體管理工具 scoop, 可以用 scoop install uv 來安裝 :

PS C:\Users\tony1> scoop install uv

Updating Scoop...

Updating Buckets...

... (略) ...

Scoop was updated successfully!

Installing 'uv' (0.9.26) [64bit] from 'main' bucket

uv-x86_64-pc-windows-msvc.zip (21.0 MB) [=====================================================================] 100%

Checking hash of uv-x86_64-pc-windows-msvc.zip ... ok.

Extracting uv-x86_64-pc-windows-msvc.zip ... done.

Linking ~\scoop\apps\uv\current => ~\scoop\apps\uv\0.9.26

Creating shim for 'uv'.

Creating shim for 'uvx'.

Creating shim for 'uvw'.

Making C:\Users\tony1\scoop\shims\uvw.exe a GUI binary.

'uv' (0.9.26) was installed successfully!

安裝完可以用 uv --version 檢查版本 :

PS C:\Users\tony1> uv --version

uv 0.9.26 (ee4f00362 2026-01-15)

關於 scoop 安裝參考 :

# 在 Windows 上安裝原生版 Claude Code

2. 常用的 uv 指令 :

uv 是一個整合 Python 版本 + 套件 + 虛擬環境管理的工具, 常用指令如下表 :

常用 uv 指令	說明
uv python list	列出本機已安裝及可供 uv 下載安裝的 Python 版本。
uv python install <version>	下載並安裝指定的 Python 版本 (例如：uv python install 3.12)。
uv python uninstall <version>	解除安裝指定的 Python 版本 (例如：uv python uninstall 3.12)。
uv python find <version>	顯示指定的 Python 版本執行檔 python.exe 之安裝路徑。
uv python dir	顯示 uv 用來存放所有下載安裝之 Python 版本的根目錄。
uv python pin <version>	鎖定當前專案所使用的 Python 版本。
uv init	初始化一個新的 Python 專案 (建立 pyproject.toml)。
uv add <package>	新增套件依賴，並自動更新 lock 檔與環境。
uv remove <package>	移除套件依賴。
uv sync	根據 uv.lock 同步專案環境 (安裝/移除套件)。
uv run <command>	在專案的虛擬環境中執行指令或腳本。
uv venv	建立一個新的虛擬環境 (預設為 .venv)。
uv pip install <package>	類似標準 pip install，用於低階套件安裝 (不建議使用)。
uv tool install <tool>	安裝全域使用的 Python 工具 (如 ruff, black)。
uv tree	顯示專案依賴關係的樹狀結構圖。
uv self update	將 uv 更新至最新版本。

注意, 在 uv 專案中不建議使用 uv pip install 來安裝套件, 雖然不會汙染系統 Python (只要不加 --system 參數就很安全), 但不會更新 pyproject.toml, 會使專案依賴清單與實際環境不符.

3. Python 版本管理 :

uv python list 會列出目前本機已安裝以及網路上可下載安裝的 Python 版本 :

PS C:\Users\tony1> uv python list

cpython-3.15.0a5-windows-x86_64-none <download available>

cpython-3.15.0a5+freethreaded-windows-x86_64-none <download available>

cpython-3.14.2-windows-x86_64-none <download available>

cpython-3.14.2+freethreaded-windows-x86_64-none <download available>

cpython-3.13.11-windows-x86_64-none <download available>

cpython-3.13.11+freethreaded-windows-x86_64-none <download available>

cpython-3.12.12-windows-x86_64-none <download available>

cpython-3.12.1-windows-x86_64-none AppData\Local\Programs\Python\Python312\python.exe

cpython-3.11.14-windows-x86_64-none <download available>

cpython-3.10.19-windows-x86_64-none <download available>

cpython-3.9.25-windows-x86_64-none <download available>

cpython-3.8.20-windows-x86_64-none <download available>

pypy-3.11.13-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>

graalpy-3.12.0-windows-x86_64-none <download available>

graalpy-3.11.0-windows-x86_64-none <download available>

graalpy-3.10.0-windows-x86_64-none <download available>

其中黃底部分即我的 LG Gram 筆電的系統 Python 3.12.1 環境, 其餘為可用 uv python install 下載安裝的版本. 可以在後面用 --only-installed 參數限制僅顯示已安裝的 Python 版本 :

PS C:\Users\tony1> uv python list --only-installed

cpython-3.12.1-windows-x86_64-none AppData\Local\Programs\Python\Python312\python.exe

注意, 使用 uv python install 安裝指定版本的 Python 環境時, uv 會將此 Python 安裝到一個獨立的隔離目錄 (通常在 %LOCALAPPDATA%\uv\python\...), 而不是安裝到 Windows 的系統路徑中, uv 也不會把這個路徑加到系統 PATH 裡. 其次, 可以同時安裝多個 Python 版本, 例如 :

uv python install 3.13 3.10

解除安裝也是可以同時解除安裝多個 Python 版本.

4. 用 uv run 執行 Python 腳本 :

先在 PS 中用 notepad 指令啟動記事本, 編輯一個 show_version.py 腳本程式 :

PS C:\Users\tony1> notepad show_version.py

輸入如下程式碼後存檔 :

import sys

print(sys.version)

用 uv 安裝的 Python 版本其執行檔位置可用 uv python find 指令找到 :

PS C:\Users\tony1> uv python find 3.12

C:\Users\tony1\AppData\Local\Programs\Python\Python312\python.exe

然後用此 python.exe 執行腳本 :

PS C:\Users\tony1> C:\Users\tony1\AppData\Local\Programs\Python\Python312\python.exe show_version.py

3.12.1 (tags/v3.12.1:2305ca5, Dec 7 2023, 22:03:25) [MSC v.1937 64 bit (AMD64)]

但不需要這麼麻煩, 用 uv run 指令即可執行 Python 程式 :

PS C:\Users\tony1> uv run show_version.py

3.12.1 (tags/v3.12.1:2305ca5, Dec 7 2023, 22:03:25) [MSC v.1937 64 bit (AMD64)]

因為我的筆電目前只有安裝 Python 3.12.1 而已, 所以 uv 會用系統 Python 來執行腳本. 如果用 uv 安裝多個 Python 版本, 則可在 uv run 後面以 --python 參數指定版本, 例如 :

uv run --python 3.12 show_version.py

PS C:\Users\tony1> uv run --python 3.12 show_version.py

3.12.1 (tags/v3.12.1:2305ca5, Dec 7 2023, 22:03:25) [MSC v.1937 64 bit (AMD64)]

5. 用 uv init 建立 Python 專案 :

uv 為了符合 Vibe Coding 的效率提供了兩種建立專案的方式, 第一種是用 mkdir 手動建立專案目錄後進入該目錄, 再用 uv init 指令建立專案檔案 :

mkdir <project_dir>

cd <project_dir>

uv init

例如 :

PS C:\Users\tony1> mkdir my_project

目錄: C:\Users\tony1

Mode LastWriteTime Length Name

---- ------------- ------ ----

d----- 2026/1/24 上午 09:51 my_project

PS C:\Users\tony1> cd my_project

PS C:\Users\tony1\my_project> uv init

Initialized project `my-project`

PS C:\Users\tony1\my_project> dir

目錄: C:\Users\tony1\my_project

Mode LastWriteTime Length Name

---- ------------- ------ ----

-a---- 2026/1/24 上午 09:51 109 .gitignore

-a---- 2026/1/24 上午 09:51 5 .python-version

-a---- 2026/1/24 上午 09:51 88 main.py

-a---- 2026/1/24 上午 09:51 156 pyproject.toml

-a---- 2026/1/24 上午 09:51 0 README.md

可見 uv init 會在專案資料夾下自動建立下面五個專案檔案 :

pyproject.toml : 專案的核心設定檔 (紀錄依賴套件與專案資訊)
.python-version : 紀錄這個專案使用的 Python 版本
main.py : 專案主程式範例
.gitignore : Git 的忽略清單 (預設會把虛擬環境與快取忽略掉)
README.md : 專案的讀我說明文件

主程式 main.py 預設是一個顯示歡迎文字的簡單範例 :

PS C:\Users\tony1\my_project> cat main.py

def main():

print("Hello from my-project!")

if __name__ == "__main__":

main()

可以用 uv run 執行看看 :

PS C:\Users\tony1\my_project> uv run main.py

Using CPython 3.12.1 interpreter at: C:\Users\tony1\AppData\Local\Programs\Python\Python312\python.exe

Creating virtual environment at: .venv

Hello from my-project!

也可以用 uv init 讓 uv 自動幫我們建立目錄與專案檔案 :

uv init <project_dir>

或指定要用的 Python 版本 :

uv init <project_dir> --python <version>

先用 rm 指令刪除上面手動建立的專案目錄 :

PS C:\Users\tony1> rm my_project -Recurse -Force

用 uv init 建立專案目錄與檔案 :

PS C:\Users\tony1> uv init my_project

Initialized project `my-project` at `C:\Users\tony1\my_project`

PS C:\Users\tony1> cd my_project

PS C:\Users\tony1\my_project> dir

目錄: C:\Users\tony1\my_project

Mode LastWriteTime Length Name

---- ------------- ------ ----

-a---- 2026/1/24 上午 10:06 109 .gitignore

-a---- 2026/1/24 上午 10:06 5 .python-version

-a---- 2026/1/24 上午 10:06 88 main.py

-a---- 2026/1/24 上午 10:06 156 pyproject.toml

-a---- 2026/1/24 上午 10:06 0 README.md

可見結果一樣.

如果用 uv init 指令指定 Python 版本建立一個專案, 例如 :

uv init --python 3.13

那麼在此專案目錄下可以用 uv run xxx.py 執行腳本, 這時就會用此專案的 Python 版本來執行腳本程式. 如果用 uv 安裝了多個版本, 則使用 uv run 指令時 uv 會按照下列順序由上而下依序尋找 python.exe 執行檔 :

專案目錄下 .python-version 檔內設定的 Python 版本
目前啟用的虛擬環境的 Python 版本
專案目錄下 .venv 資料夾內設定的虛擬環境 Python 版本
uv 自己安裝的 Python 版本
系統環境變數設定的 Python 版本

可見 .python-version 檔紀錄的 Python 版本是最優先的.

PS C:\Users\tony1\my_project> cat .python-version

3.12

6. 用 uv add 安裝套件 :

先用 uv tree 來檢視專案目錄下的套件依賴關係 :

PS C:\Users\tony1\my_project> uv tree

Using CPython 3.12.1 interpreter at: C:\Users\tony1\AppData\Local\Programs\Python\Python312\python.exe

Resolved 1 package in 5ms

my-project v0.1.0

由於目前還沒有在專案中安裝套件, 專案內還沒有虛擬環境 (.venv 子目錄不存在), 所以直接讀取了全域安裝 (System Global) 的系統 Python 3.12.

在 uv 建立的 Python 專案下, 要使用 uv add 來安裝套件, uv 會自動建立一個虛擬環境子目錄 .venv 來放套件與其依賴套件, 例如 :

PS C:\Users\tony1\my_project> uv add requests

Using CPython 3.12.1 interpreter at: C:\Users\tony1\AppData\Local\Programs\Python\Python312\python.exe

Creating virtual environment at: .venv

Resolved 6 packages in 668ms

Prepared 5 packages in 414ms

Installed 5 packages in 128ms

+ certifi==2026.1.4

+ charset-normalizer==3.4.4

+ idna==3.11

+ requests==2.32.5

+ urllib3==2.6.3

這時再用 uv tree 指令就會顯示此專案下有安裝了那些第三方套件與其依賴套件 :

PS C:\Users\tony1\my_project> uv tree

Resolved 6 packages in 2ms

my-project v0.1.0

└── requests v2.32.5

├── certifi v2026.1.4

├── charset-normalizer v3.4.4

├── idna v3.11

└── urllib3 v2.6.3

可見 requests 的四個依賴套件都掛在它下面, 這比傳統 pip list 一古腦兒列出全部套件還棒. 接下來再安裝 yfinance 與 kbar 套件, 測試一下繪製 K 線圖功能 :

PS C:\Users\tony1\my_project> uv add yfinance

Resolved 25 packages in 1.48s

Built multitasking==0.0.12

Prepared 19 packages in 11.09s

Installed 19 packages in 775ms

+ beautifulsoup4==4.14.3

+ cffi==2.0.0

+ curl-cffi==0.13.0

+ frozendict==2.4.7

+ multitasking==0.0.12

+ numpy==2.4.1

+ pandas==3.0.0

+ peewee==3.19.0

+ platformdirs==4.5.1

+ protobuf==6.33.4

+ pycparser==3.0

+ python-dateutil==2.9.0.post0

+ pytz==2025.2

+ six==1.17.0

+ soupsieve==2.8.3

+ typing-extensions==4.15.0

+ tzdata==2025.3

+ websockets==16.0

+ yfinance==1.0

PS C:\Users\tony1\my_project> uv add kbar

Resolved 35 packages in 2.10s

Prepared 11 packages in 6.29s

Uninstalled 1 package in 134ms

Installed 11 packages in 581ms

+ contourpy==1.3.3

+ cycler==0.12.1

+ fonttools==4.61.1

+ kbar==0.1.5

+ kiwisolver==1.4.9

+ matplotlib==3.10.8

+ mplfinance==0.12.10b0

+ packaging==26.0

- pandas==3.0.0

+ pandas==2.3.3

+ pillow==12.1.0

+ pyparsing==3.3.2

再次用 uv tree 顯示已安裝套件 :

PS C:\Users\tony1\my_project> uv tree

Resolved 35 packages in 2ms

my-project v0.1.0

├── kbar v0.1.5

│ ├── matplotlib v3.10.8

│ │ ├── contourpy v1.3.3

│ │ │ └── numpy v2.4.1

│ │ ├── cycler v0.12.1

│ │ ├── fonttools v4.61.1

│ │ ├── kiwisolver v1.4.9

│ │ ├── numpy v2.4.1

│ │ ├── packaging v26.0

│ │ ├── pillow v12.1.0

│ │ ├── pyparsing v3.3.2

│ │ └── python-dateutil v2.9.0.post0

│ │ └── six v1.17.0

│ ├── mplfinance v0.12.10b0

│ │ ├── matplotlib v3.10.8 (*)

│ │ └── pandas v2.3.3

│ │ ├── numpy v2.4.1

│ │ ├── python-dateutil v2.9.0.post0 (*)

│ │ ├── pytz v2025.2

│ │ └── tzdata v2025.3

│ ├── numpy v2.4.1

│ └── pandas v2.3.3 (*)

├── requests v2.32.5

│ ├── certifi v2026.1.4

│ ├── charset-normalizer v3.4.4

│ ├── idna v3.11

│ └── urllib3 v2.6.3

└── yfinance v1.0

├── beautifulsoup4 v4.14.3

│ ├── soupsieve v2.8.3

│ └── typing-extensions v4.15.0

├── curl-cffi v0.13.0

│ ├── certifi v2026.1.4

│ └── cffi v2.0.0

│ └── pycparser v3.0

├── frozendict v2.4.7

├── multitasking v0.0.12

├── numpy v2.4.1

├── pandas v2.3.3 (*)

├── peewee v3.19.0

├── platformdirs v4.5.1

├── protobuf v6.33.4

├── pytz v2025.2

├── requests v2.32.5 (*)

└── websockets v16.0

(*) Package tree already displayed

執行記事本程式編輯 main.py :

PS C:\Users\tony1\my_project> notepad main.py

將 main.py 改成如下 :

from kbar import KBar

import yfinance as yf

def main():

df=yf.download('0050.TW', start='2024-07-01', end='2024-08-21', auto_adjust=False)

df.columns=df.columns.map(lambda x: x[0]) # 改成舊版單層索引

kb=KBar(df) # 未傳 font 參數預設使用正黑體

kb.plot(title='台灣五十(0050.TW)', volume=True)

if __name__ == "__main__":

main()

用 uv run 執行 main.py :

PS C:\Users\tony1\my_project> uv run main.py

[*********************100%***********************] 1 of 1 completed

設定字型為: Microsoft JhengHei

使用指定字型: Microsoft JhengHei

字型候選清單: ['Microsoft JhengHei', 'DejaVu Sans', 'Arial']

可見順利繪製了 K 線圖.

7. 建立 uv 專案的標準流程 :

最後將 uv 建立 Python 專案的流程摘要整理如下 :

(1). 建立並初始化專案 :

直接指定專案名稱與 Python 版本一步到位 :

# 建立一個名為 my_project 的專案, 並指定使用 Python 3.12

uv init my_project --python 3.12

# 進入專案目錄

cd my_project

(2). 安裝套件 (關鍵步驟) :

如果還沒有虛擬環境會自動建立 .venv 子目錄, 然後下載並安裝套件到虛擬環境中 (可以一次安裝多個套件), 最後將套件依賴寫入 pyproject.toml 方便以後管理 :

uv add requests yfinace kbar

(3). 執行程式 :

不需要先啟動虛擬環境直接用 uv run, 它會自己去用專案裡的環境跑 (假設主程式為 main.py) :

uv run main.py

(4). 同步環境 (可選) :

如果是從 Github 下載別人的 uv 專案或者換了電腦, 需要執行 uv sync 指令, 它會根據鎖定檔 (uv.lock) 把整個虛擬環境還原回來 :

uv sync

最後來看一下 .venv 子目錄內容 :

PS C:\Users\tony1\my_project> dir .venv

目錄: C:\Users\tony1\my_project\.venv

Mode LastWriteTime Length Name

---- ------------- ------ ----

d----- 2026/1/24 上午 11:22 Lib

d----- 2026/1/24 下午 12:36 Scripts

d----- 2026/1/24 下午 12:36 share

-a---- 2026/1/24 上午 11:22 1 .gitignore

-a---- 2026/1/24 上午 11:22 0 .lock

-a---- 2026/1/24 上午 11:22 43 CACHEDIR.TAG

-a---- 2026/1/24 上午 11:22 178 pyvenv.cfg

我們用 uv add 安裝的套件都會放在 Lib\site-packages 裡面.

沒有留言 :

張貼留言

訂閱：張貼留言 ( Atom )

小狐狸事務所

2026年1月24日星期六

Python 學習筆記 : 整合型 Python 版本管理工具 uv

沒有留言 :

文章標籤

常用連結

2026年1月24日 星期六

Python 學習筆記 : 整合型 Python 版本管理工具 uv

沒有留言 :

2026年1月24日星期六