快捷導(dǎo)航

如何使用uv構(gòu)建Python包并本地安裝步驟詳解

更新時(shí)間：2025年06月06日 10:05:13 作者：夢想畫家

uv是一個(gè)由Astral開發(fā)的超快Python包安裝工具和解析器,使用Rust編寫,旨在替代pip、pip-tools和virtualenv,提供更快的性能和更好的依賴管理,這篇文章主要介紹了如何使用uv構(gòu)建Python包并本地安裝的相關(guān)資料,需要的朋友可以參考下

前言

本文將逐步指導(dǎo)你創(chuàng)建一個(gè)簡單的 Python 包，并將其本地安裝到機(jī)器或云環(huán)境中。完成本教程后，你將擁有一個(gè)可復(fù)用的 Python 庫，可直接通過 pip 安裝或在項(xiàng)目中導(dǎo)入使用。

步驟詳解

Step 0: 選擇構(gòu)建工具 - 使用 uv

推薦理由：uv 是類似 poetry 的現(xiàn)代打包工具，默認(rèn)使用 hatchling 作為構(gòu)建后端，支持 PEP 517/518 標(biāo)準(zhǔn)。

安裝方法：

# 通過 Homebrew 安裝（MacOS）
brew install uv
# 或直接通過 PyPI
pip install uv

Step 1: 創(chuàng)建包目錄結(jié)構(gòu)

使用 uv 快速初始化項(xiàng)目結(jié)構(gòu)：

uv init --lib my-package

生成后的目錄如下：

my_package/
├── src/
│   └── my_package/
│       ├── __init__.py       # 標(biāo)記為 Python 包
│       └── your_code.py      # 存放核心代碼
│       └── py.typed          # 類型標(biāo)注聲明（可選）
├── pyproject.toml          # 項(xiàng)目元數(shù)據(jù)和依賴配置
├── README.md               # 項(xiàng)目文檔
└── .python-version         # 指定 Python 版本

Step 2: 編寫包代碼

在 src/my_package/your_code.py 中添加功能代碼：

# my_package/your_code.py
def greet(name: str) -> str:
    """返回問候語"""
    return f"Hello, {name}!"

Step 3: 配置 pyproject.toml

填寫項(xiàng)目元數(shù)據(jù)和依賴項(xiàng)：

[project]
name = "my-package"
version = "0.1.0"
description = "一個(gè)簡單的本地 Python 包示例"
readme = "README.md"
authors = [{ name = "Sarah Glasmacher", email = "sarah@example.com" }]
requires-python = ">=3.11"
dependencies = []

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

Step 4: 構(gòu)建分發(fā)包

運(yùn)行以下命令生成 .whl 或 .tar.gz 文件：

uv build

構(gòu)建完成后，dist/ 目錄下會(huì)生成類似以下的文件：

dist/
├── my_package-0.1.0-py3-none-any.whl
└── my_package-0.1.0.tar.gz

Step 5: 本地安裝包

方法 1：直接安裝構(gòu)建產(chǎn)物

pip install dist/my_package-0.1.0-py3-none-any.whl

方法 2：以編輯模式安裝（實(shí)時(shí)同步代碼）

pip install -e .

Step 6: 測試安裝

打開 Python 終端驗(yàn)證：

from my_package.your_code import greet
print(greet("World"))  # 輸出：Hello, World!

關(guān)鍵注意事項(xiàng)

模塊化設(shè)計(jì)：將代碼按功能拆分為獨(dú)立模塊，便于維護(hù)和復(fù)用。
依賴管理：通過 dependencies 字段聲明依賴，或使用 uv add <package> 自動(dòng)更新 pyproject.toml。
版本控制：每次發(fā)布新版本前更新 version 字段，避免沖突。