星期日, 8月 24, 2025

UV 安裝與測試小記


UV 安裝與測試小記


OS: macOS 14.3

uv: 0.8.13


最近規劃後續要多放點時間在程式上, 初步會從 python 來起手

之前看 Colab 上面的練習, 跟python 有關的會使用 uv 來進行環境的安裝, 目前自己在 python 的使用是 python + pip + venv, 所以今天就來安裝 uv 體驗一下


uv 的官網


官網的文件非常齊全, 建議可以多從這邊看與練習

另外我也有參考網路上面的文章以及 youtube 影片


首先我們來安裝 uv

  • 官方建議的方式是 curl -LsSf https://astral.sh/uv/install.sh | sh


我這邊用的是使用 brew 安裝

% brew  install  uv


確認安裝的版本

% uv  --version


uv 0.8.13 (Homebrew 2025-08-21)

另外來處理 zsh 自動完成指令設定


開啟一個新的終端機測試, 就會發現使用 tab 會自動完成


來執行相關指令測試


列出可用的 python 版本

% uv  python  list


cpython-3.14.0rc2-macos-aarch64-none                 <download available>

cpython-3.14.0rc2+freethreaded-macos-aarch64-none    <download available>

cpython-3.13.7-macos-aarch64-none                    <download available>

cpython-3.13.7+freethreaded-macos-aarch64-none       <download available>

cpython-3.12.11-macos-aarch64-none                   /opt/homebrew/bin/python3.12 -> ../Cellar/python@3.12/3.12.11/bin/python3.12

cpython-3.12.11-macos-aarch64-none                   <download available>

cpython-3.11.13-macos-aarch64-none                   <download available>

cpython-3.11.6-macos-aarch64-none                    /usr/local/bin/python3.11 -> ../../../Library/Frameworks/Python.framework/Versions/3.11/bin/python3.11

cpython-3.11.6-macos-aarch64-none                    /usr/local/bin/python3 -> ../../../Library/Frameworks/Python.framework/Versions/3.11/bin/python3

cpython-3.10.18-macos-aarch64-none                   <download available>

cpython-3.9.23-macos-aarch64-none                    <download available>

cpython-3.9.6-macos-aarch64-none                     /usr/bin/python3

cpython-3.8.20-macos-aarch64-none                    <download available>

pypy-3.11.13-macos-aarch64-none                      <download available>

pypy-3.10.16-macos-aarch64-none                      <download available>

pypy-3.9.19-macos-aarch64-none                       <download available>

pypy-3.8.16-macos-aarch64-none                       <download available>

graalpy-3.11.0-macos-aarch64-none                    <download available>

graalpy-3.10.0-macos-aarch64-none                    <download available>

graalpy-3.8.5-macos-aarch64-none                     <download available>


列出已安裝的版本

% uv  python  find                                       


/opt/homebrew/opt/python@3.12/bin/python3.12


  • 比對上方的可用 python 版本, 應該是針對 uv 已經安裝的版本, 版本為 3.12


另外有一個重要的點是 uv 管理的 python 環境不能直接透過 python 指令執行，必須透過 uv 來執行.


這邊我使用跟網路上找到文章一樣的例子


建立一個 python 檔案 show_version.py

內容如下


# 匯入 sys 模組，此模組提供存取由 Python 解譯器使用或維護的變數，以及與解譯器互動的函式

import sys

# 印出 Python 解譯器的版本資訊字串

print(sys.version)


首先觀察

% which  python3


/usr/local/bin/python3


% ls  -l  /usr/local/bin/python3


lrwxr-xr-x  1 root  wheel  70  9 21  2024 /usr/local/bin/python3 -> ../../../Library/Frameworks/Python.framework/Versions/3.11/bin/python3


這個時候可以知道目前 python3 指令其實是對到 3.11 版本


所以如果我們用 python3 指令去執行 show_version.py

輸出如下


% python3  show_version.py 


3.11.6 (v3.11.6:8b6ee5ba3b, Oct  2 2023, 11:18:21) [Clang 13.0.0 (clang-1300.0.29.30)]


剛剛 uv 裝起來預設的 python 版本是 3.12


如果要使用 uv 那個版本的 python 來執行, 要使用 uv run 指令來執行


% uv  run  show_version.py 


3.12.11 (main, Jun  3 2025, 15:41:47) [Clang 16.0.0 (clang-1600.0.26.6)]


另外補充一個詢問 gemini code assist 的資訊

  • uv python find：探索與發現。它會掃描您的整個系統，找出 所有 可用的 Python 解譯器，無論是系統內建的、透過 pyenv 或 asdf 管理的，還是您手動安裝的。

  • uv python list --only-installed：管理與檢視。它 只會 列出透過 uv 指令自己安裝和管理的 Python 解譯器。


使用 uv 執行 python script


建立一個檔案 rich_demo.py 內容如下


# 匯入 time 模組，用於處理時間相關的操作，例如暫停程式執行

import time

# 從 rich.progress 模組匯入 track 函式，這是一個方便的函式，可以輕鬆地為迴圈加上進度條

from rich.progress import track


# 使用 for 迴圈迭代 20 次

# track() 函式會自動包裝可迭代物件 (這裡是 range(20))，並在終端機中顯示一個視覺化的進度條

# description 參數可以設定顯示在進度條前方的文字

for i in track(range(20), description="For example:"):

   # 在迴圈的每一次迭代中，讓程式暫停 0.05 秒

   # 這是為了模擬正在執行的工作，並讓我們能清楚地看到進度條的動畫效果

   time.sleep(0.05)


使用 uv 執行


% uv  run --no-project  rich_demo.py 


Traceback (most recent call last):

  File "/Users/max/Downloads/local_lab/python/rich_demo.py", line 4, in <module>

    from rich.progress import track

ModuleNotFoundError: No module named 'rich'


  • 這邊會失敗的原因是因為我們沒有 rich 這個套件


等等我們會使用 --with 的方式來執行, 執行之前先觀察 暫存目錄


% uv  cache  dir


/Users/max/.cache/uv


% ls  /Users/max/.cache/uv


CACHEDIR.TAG   interpreter-v4 sdists-v9


% uv  run  --with  rich  rich_demo.py


For example: ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:01


  • 使用 --with 來暫時的安裝套件 rich 來執行 


再次觀察可以發現 rich 套件於快取目錄內


% find /Users/max/.cache/uv/ -name 'rich'


/Users/max/.cache/uv//wheels-v5/pypi/rich

/Users/max/.cache/uv//archive-v0/4i2npuzGKTAaTSJr7KHgL/lib/python3.12/site-packages/rich

/Users/max/.cache/uv//archive-v0/PSjqC35p_rN0sqABiq9-f/rich


接下來測試 project 相關


使用 uv init 指令建立 project


% uv  init  hello-world


Initialized project `hello-world` at `/Users/max/Downloads/local_lab/python/hello-world`


  • hello-world 是專案名稱


這邊透過 vscode 看會比教直觀



  • main.py - 一個範例的 hello world 檔案

  • .python-version - 確認使用的 python 版本

  • pyproject.toml - 設定專案相關資訊, 主要是有 dependencies 設定可以將套件相依性進行紀錄與處理


我們切換到 hello-world 目錄

% cd  hello-world


main.py 只是列印  hello-world 出來, 我們嘗試使用 uv run 來執行他


% uv  run  main.py


Using CPython 3.12.11 interpreter at: /opt/homebrew/opt/python@3.12/bin/python3.12

Creating virtual environment at: .venv

Hello from hello-world!


  • 這邊可以看到當我們執行 uv run 的時候, uv 會自動建立 .venv 的虛擬環境


再次觀察目錄



  • 這邊會看到有建立 .venv 目錄以及 uv.lock 

  • .venv 是虛擬環境 - 這邊看到的好處是 uv 會自動建立 .venv 

  • uv.lock 功用: uv.lock 檔案是由 uv 這個 Python 套件管理工具所產生的一個鎖定檔案 (lock file)。它的核心功能是記錄您專案所依賴的每一個套件的確切版本號。這不僅包括您在 pyproject.toml 或 requirements.txt 中直接指定的套件，也包括這些套件所依賴的間接套件（也就是所謂的 "sub-dependencies"）。


嘗試把剛剛的 rich_demo.py 複製到這個專案


% uv  run  rich_demo.py 


Traceback (most recent call last):

  File "/Users/max/Downloads/local_lab/python/hello-world/rich_demo.py", line 4, in <module>

    from rich.progress import track

ModuleNotFoundError: No module named 'rich'


  • 因為目前沒有 rich 套件, 所以會產生錯誤


與之前執行 python script 不同, 我們使用 uv add 指令來增加套件


% uv  add  rich


Resolved 5 packages in 293ms

Prepared 4 packages in 483ms

Installed 4 packages in 9ms

 + markdown-it-py==4.0.0

 + mdurl==0.1.2

 + pygments==2.19.2

 + rich==14.1.0


這個時候去觀察 .venv 目錄就發現 rich 套件已經被加入到虛擬環境中

% ls  ./.venv/lib/python3.12/site-packages 


__pycache__                    markdown_it                    mdurl-0.1.2.dist-info          rich

_virtualenv.pth                markdown_it_py-4.0.0.dist-info pygments                       rich-14.1.0.dist-info

_virtualenv.py                 mdurl                          pygments-2.19.2.dist-info


再次執行就可以運作

% uv  run  rich_demo.py

                    

For example: ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:01


另外同步觀察 pyproject.toml


[project]

name = "hello-world"

version = "0.1.0"

description = "Add your description here"

readme = "README.md"

requires-python = ">=3.12"

dependencies = [

   "rich>=14.1.0",

]

  • 可以觀察到 rich 已經被寫入 dependencies


也可以使用 uv tree 觀察相關資訊


% uv  tree


Resolved 5 packages in 17ms

hello-world v0.1.0

└── rich v14.1.0

    ├── markdown-it-py v4.0.0

    │   └── mdurl v0.1.2

    └── pygments v2.19.2


另外如果針對都會使用到工具指令 可以使用 uv tool install 來安裝到 全域, 讓整個系統可用, uv 會使用獨立的路徑避免衝突



這邊使用 ruff 測試


還沒安裝之前

% ruff

zsh: command not found: ruff


% uv tool install ruff


Resolved 1 package in 773ms

Prepared 1 package in 684ms

Installed 1 package in 13ms

 + ruff==0.12.10

Installed 1 executable: ruff

warning: `/Users/max/.local/bin` is not on your PATH. To use installed tools, run `export PATH="/Users/max/.local/bin:$PATH"` or `uv tool update-shell`.

  • 如同上面提示, 目前 ruff 所以安裝的目錄位置並沒有在路徑變數, 所以可能要使用 export 或是 uv tool update-shell 來更新才能執行


% uv tool update-shell 


Created configuration file: /Users/max/.zshenv

Restart your shell to apply changes


開啟一個新的 shell 測試

% ruff  check


All checks passed!


可以使用 uv tool list 來檢查已經安裝的工具

% uv  tool  list


ruff v0.12.10

- ruff


以上是今天的小測試, 感覺又離 python 前進一步


~ enjoy it



References
張貼者： 於 沒有留言:
標籤：
訂閱： 文章 (Atom)