managing-python-projects-with-uv

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Managing Python Projects with uv

使用uv管理Python项目

Overview

概述

This skill helps you work with Python projects managed by uv, an extremely fast Python package and project manager written in Rust. Use this skill for:

Initializing new Python projects
Managing dependencies and virtual environments
Running scripts and applications
Building and publishing packages
Optimizing Python workflows with uv's speed
There are several ways to install and use Python and the ecosystem built upon Python.
- PyEnv has been available for a while and is now mature enough to be widely used by the majority of users. PyEnv is the solution be default used in these cheat sheets
- uv is the new, shiny, kid on the block, and may appeal to those seeking to be on the edge of technological trends. There is at least a very specific use case where uv proves useful, it is to power standalone Python scripts: it is enough to add the magic
```
#!/usr/bin/env -S uv
```
  command as the first line of any Python script, and that latter becomes standalone, self-served on any platform, any where, whithout requiring the users to install anything like dependencies (apart uv itself, obviously)

本技能可帮助你使用由Rust编写的超快速Python包和项目管理器uv来管理Python项目。可用于以下场景：

初始化新的Python项目
管理依赖和虚拟环境
运行脚本和应用程序
构建并发布包
借助uv的速度优化Python工作流
有多种安装和使用Python及其生态系统的方式。
- PyEnv已经出现一段时间，现在足够成熟，被大多数用户广泛使用。在这些速查表中，PyEnv是默认使用的解决方案
- uv是新兴的热门工具，可能吸引那些追求技术前沿趋势的用户。uv至少在一个特定场景下非常有用：为独立Python脚本提供支持。只需在任意Python脚本的第一行添加魔法命令
```
#!/usr/bin/env -S uv
```
  ，该脚本就会成为独立的自包含脚本，可在任何平台、任何环境下运行，无需用户安装依赖项（显然，除了uv本身）

When to Use This Skill

何时使用本技能

Use this skill when:

Setting up a new Python project from scratch
Converting an existing project to use uv
Managing dependencies (adding, removing, updating packages)
Working with virtual environments
Running Python scripts or applications in a uv project
Building distributions for PyPI
The user asks about uv commands or workflows
You need to check which Python version or packages are installed

在以下场景使用本技能：

从零开始搭建新的Python项目
将现有项目转换为使用uv
管理依赖（添加、移除、更新包）
处理虚拟环境
在uv项目中运行Python脚本或应用程序
构建用于PyPI的发行版
用户询问uv命令或工作流
你需要检查已安装的Python版本或包

Additional Resources

其他资源

Assets for this skill

本技能相关资源

Makefile — Example of Makefile excerpts with relevant targets
pyproject.toml — Example of Python project file, compatible with uv
README.md — Example of relevant excerpts in the README file
main.py — Example of working standalone main.py file, to be copied in the
```
src/<project>/
```
directory (if not existing, be sure to create that directory, adapting to your project)
```
test_main.py
```
— Example of working
```
test_main.py
```
Python test script, to be copied in the
```
tests/
```
directory (if not existing, be sure to create that directory)
.gitignore - Example of relevant excerpts in the
```
.gitignore
```
file, Git-ignoring Python-/uv-related files
ci.yml - Example of relevant excerpts in the
```
ci.yml
```
CI/CD (GitHub Actions) pipeline, to be copied into the
```
.github/workflows/
```
directory (if not existing, be sure to create that directory)

Makefile — 包含相关目标的Makefile示例片段
pyproject.toml — 兼容uv的Python项目文件示例
README.md — README文件中的相关示例片段
main.py — 可运行的独立main.py文件示例，需复制到
```
src/<project>/
```
目录（如果该目录不存在，请创建并适配你的项目）
```
test_main.py
```
— 可运行的
```
test_main.py
```
Python测试脚本示例，需复制到
```
tests/
```
目录（如果该目录不存在，请创建）
.gitignore — .gitignore文件中的相关示例片段，忽略与Python/uv相关的文件
ci.yml — CI/CD（GitHub Actions）流水线ci.yml的相关示例片段，需复制到
```
.github/workflows/
```
目录（如果该目录不存在，请创建）

Data Engineering Helpers

数据工程助手

Data Engineering Helpers - Knowledge Sharing - Python - Cheat sheet for how to set up and use Python, especially detailing the installation and use of uv

Data Engineering Helpers - 知识分享 - Python — Python设置和使用的速查表，详细介绍了uv的安装和使用

uv

uv相关

Quick Reference

快速参考

Integrate the sample files into your project directory (if you had not any such file, just copy them; otherwise, merge their content within your corresponding files):
- Makefile
- pyproject.toml compatible with uv
- README.md
- main.py
- ```
test_main.py
```
- .gitignore
- ci.yml

将示例文件集成到你的项目目录中（如果没有对应文件，直接复制；否则，将内容合并到现有文件中）：
- Makefile
- pyproject.toml（兼容uv）
- README.md
- main.py
- ```
test_main.py
```
- .gitignore
- ci.yml

Quick start

快速开始

If not already done so, install a specific Python version for uv:

bash

make init-uv-python PYTHON_VERSION=3.13

Clean all previous work:

bash

make clean

Note that uv is expecting that the Python source code be in the
```
src/<project>/
```
sub-directory
- The
```
<project>
```
  name is specified in the pyproject.toml Python project specification file. Change it to reflect your project name
- For the next commands to work, that source directory should at least contain a Python script. If need, copy the main.py into the
```
src/<project>/
```
  directory:

bash

mkdir -p src/<project> tests .github/workflows
cp assets/main.py src/<project>/
cp assets/test_main.py tests/
cp assets/ci.yml .github/workflows/
git add src/<project>/main.py tests/test_main.py .github/workflows/ci.yml

Initialize the Python environment with uv:

bash

make init update

Run the Python script:

bash

make run

如果尚未安装，为uv安装特定版本的Python：

bash

make init-uv-python PYTHON_VERSION=3.13

清理之前的所有工作：

bash

make clean

注意，uv要求Python源代码位于
```
src/<project>/
```
子目录中
- ```
<project>
```
  名称在pyproject.tomlPython项目配置文件中指定。请修改它以匹配你的项目名称
- 为使后续命令正常工作，该源目录至少应包含一个Python脚本。如果需要，将main.py复制到
```
src/<project>/
```
  目录：

bash

mkdir -p src/<project> tests .github/workflows
cp assets/main.py src/<project>/
cp assets/test_main.py tests/
cp assets/ci.yml .github/workflows/
git add src/<project>/main.py tests/test_main.py .github/workflows/ci.yml

使用uv初始化Python环境：

bash

make init update

运行Python脚本：

bash

make run

Useful commands

实用命令

Build the artifact (Python wheel):

bash

make build

Check (with the linter and type checkers) that there is no Python issue:

bash

make check

Test the Python package:

bash

make test

Publish the artifact (Python wheel):

bash

make publish

构建产物（Python wheel）：

bash

make build

检查（使用代码检查器和类型检查器）是否存在Python问题：

bash

make check

测试Python包：

bash

make test

发布产物（Python wheel）：

bash

make publish