Python 项目管理#

安装 uv．

管理 Python#

下载 Python，并查看本机已安装的 Python：

1
PS C:\Users\Shy_Vector\AAA> uv python install pypy
2
PS C:\Users\Shy_Vector\AAA> uv python list

1
cpython-3.15.0a6-windows-x86_64-none                 <download available>
2
cpython-3.15.0a6+freethreaded-windows-x86_64-none    <download available>
3
cpython-3.14.3-windows-x86_64-none                   <download available>
4
cpython-3.14.3+freethreaded-windows-x86_64-none      <download available>
5
cpython-3.13.12-windows-x86_64-none                  <download available>
6
cpython-3.13.12+freethreaded-windows-x86_64-none     <download available>
7
cpython-3.12.13-windows-x86_64-none                  <download available>
8
cpython-3.12.10-windows-x86_64-none                  C:\Program Files\Python\python.exe
9
cpython-3.11.15-windows-x86_64-none                  <download available>
10
cpython-3.10.20-windows-x86_64-none                  <download available>
11
cpython-3.9.25-windows-x86_64-none                   <download available>
12
cpython-3.8.20-windows-x86_64-none                   <download available>
13
pypy-3.11.13-windows-x86_64-none                     C:\Users\Shy_Vector\AppData\Roaming\uv\python\pypy-3.11.13-windows-x86_64-none\pypy3.11.exe
14
pypy-3.10.16-windows-x86_64-none                     <download available>
15
pypy-3.9.19-windows-x86_64-none                      <download available>
16
pypy-3.8.16-windows-x86_64-none                      <download available>
17
graalpy-3.12.0-windows-x86_64-none                   <download available>
18
graalpy-3.11.0-windows-x86_64-none                   <download available>
19
graalpy-3.10.0-windows-x86_64-none                   <download available>

临时运行特定版本的 Python / 脚本：

1
PS C:\Users\Shy_Vector\AAA> uv run -p 3.12 python
2

3
Python 3.12.10 (tags/v3.12.10:0cc8128, Apr  8 2025, 12:21:36) [MSC v.1943 64 bit (AMD64)] on win32
4
Type "help", "copyright", "credits" or "license" for more information.
5
Ctrl click to launch VS Code Native REPL
6
>>> exit()
7

8
PS C:\Users\Shy_Vector\AAA> uv run -p pypy python
9

10
Python 3.11.13 (413c9b7f57f5, Jul 03 2025, 18:04:37)
11
[PyPy 7.3.20 with MSC v.1941 64 bit (AMD64)] on win32
12
Type "help", "copyright", "credits" or "license" for more information.
13
Ctrl click to launch VS Code Native REPL
14
>>>> exit()

删除 Python：

1
PS C:\Users\Shy_Vector\AAA> uv python uninstall pypy

1
Searching for Python versions matching: PyPy
2
Uninstalled Python 3.11.13 in 777ms
3
 - pypy-3.11.13-windows-x86_64-none

管理 venv#

初始化项目：

1
PS C:\Users\Shy_Vector\AAA> uv init -p 3.12
2

3
Initialized project `AAA`
4

5
PS C:\Users\Shy_Vector\AAA> ls
6

7
    目录: C:\Users\Shy_Vector\AAA
8

9
Mode                 LastWriteTime         Length Name
10
----                 -------------         ------ ----
11
-a----          2026/3/4     10:53            109 .gitignore
12
-a----          2026/3/4     10:53              5 .python-version
13
-a----          2026/3/4     10:46            167 main.py
14
-a----          2026/3/4     10:53            154 pyproject.toml
15
-a----          2026/3/4     10:53              0 README.md

可在 .python-version 中修改当前项目的 Python 版本：

1
3.12

pyproject.toml 包含当前项目的配置信息，第三方工具零散的配置文件得到统一：

1
[project]
2
name = "AAA"
3
version = "0.1.0"
4
description = "AAAAAA"
5
readme = "README.md"
6
requires-python = ">=3.12"
7
dependencies = []

初始化之前已有 main.py，

1
from flask import Flask
2

3
app = Flask(__name__)
4

5
@app.route('/')
6
def foo():
7
    return 'Hello World'
8

9
if __name__ == '__main__':
10
    app.run(debug=True)

里面依赖了 flask 第三方库，接下来我们安装它：

1
PS C:\Users\Shy_Vector\AAA> uv add flask

1
Using CPython 3.12.10 interpreter at: C:\Program Files\Python\python.exe
2
Creating virtual environment at: .venv
3
Resolved 9 packages in 1.41s
4
Prepared 8 packages in 533ms
5
Installed 8 packages in 26ms
6
 + blinker==1.9.0
7
 + click==8.3.1
8
 + colorama==0.4.6
9
 + flask==3.1.3
10
 + itsdangerous==2.2.0
11
 + jinja2==3.1.6
12
 + markupsafe==3.0.3
13
 + werkzeug==3.1.6

--dev
对于 uv add 的参数，可以使用 --dev 参数将工具加入开发依赖组，组内的依赖仅在开发阶段被使用，不会被打包出去．
Terminal window
1
uv add ruff --dev
.pyproject.toml
1
[project]
2
name = "AAA"
3
version = "0.1.0"
4
description = "AAAAAA"
5
readme = "README.md"
6
requires-python = ">=3.12"
7
dependencies = [
8
    "flask>=3.1.3",
9
]
10

11
[dependency-groups]
12
dev = [
13
    "ruff>=0.15.4",
14
]
当然，ruff 是工具而不是依赖，与工程代码无关，不应该作为依赖引入．
Terminal window
1
uv remove ruff --dev

uv tool

对于工具，可以使用 uv tool install 来安装：

1
PS C:\Users\Shy_Vector\AAA> uv tool install ruff
2
Resolved 1 package in 265ms
3
Installed 1 package in 15ms
4
 + ruff==0.15.4
5
Installed 1 executable: ruff
6
PS C:\Users\Shy_Vector\AAA> which ruff
7
C:\Users\Shy_Vector\.local\bin\ruff.EXE
8
PS C:\Users\Shy_Vector\AAA> ruff check
9
All checks passed!

查看所有工具：

1
PS C:\Users\Shy_Vector\AAA> uv tool list
2
ruff v0.15.4
3
- ruff

我们可以看到 uv 已经为当前项目自动创建虚拟环境 .venv：

1
PS C:\Users\Shy_Vector\AAA> tree

1
文件夹 PATH 列表
2
卷序列号为 EA1E-9D15
3
C:.
4
├─.ruff_cache
5
│  └─0.15.4
6
└─.venv
7
    ├─Lib
8
    │  └─site-packages
9
    │      ├─blinker
10
    │      │  └─__pycache__
11
    │      ├─blinker-1.9.0.dist-info
12
    │      ├─click
13
    │      │  └─__pycache__
14
    │      ├─click-8.3.1.dist-info
15
    │      │  └─licenses
16
    │      ├─colorama
17
    │      │  ├─tests
18
    │      │  └─__pycache__
19
    │      ├─colorama-0.4.6.dist-info
20
    │      │  └─licenses
21
    │      ├─flask
22
    │      │  ├─json
23
    │      │  │  └─__pycache__
24
    │      │  ├─sansio
25
    │      │  │  └─__pycache__
26
    │      │  └─__pycache__
27
    │      ├─flask-3.1.3.dist-info
28
    │      │  └─licenses
29
    │      ├─itsdangerous
30
    │      │  └─__pycache__
31
    │      ├─itsdangerous-2.2.0.dist-info
32
    │      ├─jinja2
33
    │      │  └─__pycache__
34
    │      ├─jinja2-3.1.6.dist-info
35
    │      │  └─licenses
36
    │      ├─markupsafe
37
    │      │  └─__pycache__
38
    │      ├─markupsafe-3.0.3.dist-info
39
    │      │  └─licenses
40
    │      ├─werkzeug
41
    │      │  ├─datastructures
42
    │      │  │  └─__pycache__
43
    │      │  ├─debug
44
    │      │  │  ├─shared
45
    │      │  │  └─__pycache__
46
    │      │  ├─middleware
47
    │      │  ├─routing
48
    │      │  │  └─__pycache__
49
    │      │  ├─sansio
50
    │      │  │  └─__pycache__
51
    │      │  ├─wrappers
52
    │      │  │  └─__pycache__
53
    │      │  └─__pycache__
54
    │      ├─werkzeug-3.1.6.dist-info
55
    │      │  └─licenses
56
    │      └─__pycache__
57
    └─Scripts

虚拟环境何以实现？
当虚拟环境被激活后，.venv\\Lib\\site-packages 目录将被追加进 Python 中 sys.path 列表：
1
>>> import sys, pprint
2
>>> pprint.pp(sys.path)
3
['',
4
 'C:\\Program Files\\Python\\python312.zip',
5
 'C:\\Program Files\\Python\\DLLs',
6
 'C:\\Program Files\\Python\\Lib',
7
 'C:\\Program Files\\Python',
8
 'C:\\Users\\Shy_Vector\\AAA\\.venv',
9
 'C:\\Users\\Shy_Vector\\AAA\\.venv\\Lib\\site-packages']
Python 在导入模块时，将逐个检查 sys.path 列表里的每个路径，直到找出该模块．

查看所有第三方库的依赖关系：

1
PS C:\Users\Shy_Vector\AAA> uv tree

1
Resolved 9 packages in 1ms
2
AAA v0.1.0
3
└── flask v3.1.3
4
    ├── blinker v1.9.0
5
    ├── click v8.3.1
6
    │   └── colorama v0.4.6
7
    ├── itsdangerous v2.2.0
8
    ├── jinja2 v3.1.6
9
    │   └── markupsafe v3.0.3
10
    ├── markupsafe v3.0.3
11
    └── werkzeug v3.1.6
12
        └── markupsafe v3.0.3

现在运行 main.py：

1
PS C:\Users\Shy_Vector\AAA> uv run main.py
2
 * Serving Flask app 'main'
3
 * Debug mode: on
4
WARNING: This is a development server. Do not use it in a production deployment. Use a production WSGI server instead.
5
 * Running on http://127.0.0.1:5000
6
Press CTRL+C to quit
7
 * Restarting with stat
8
 * Debugger is active!
9
 * Debugger PIN: 329-036-685
10
127.0.0.1 - - [04/Mar/2026 10:59:36] "GET / HTTP/1.1" 200 -

我拿到的是别人的项目，怎么配环境？
难不成只能看 pyproject.toml，一个个手动 uv add？当然不需要！只需
Terminal window
1
PS C:\Users\Shy_Vector\AAA> uv sync
uv 就会读取 pyproject.toml，自动搭建虚拟环境，并安装好所有依赖．

Python 往事
如果只用 Python 官方的工具管理项目，那么流程是：手动创建虚拟环境 .venv 并激活，编辑并读取 pyproject.toml，往 .venv 安装依赖．
Terminal window
1
python -m venv .venv
2
source .venv/bin/activate (.venv\\Scripts\\activate)
3
edit pyproject.toml
4
pip install -e .
.venv 可以取别的名字，但 .venv 这个名字已经被各界认同，也便于 IDE 识别．

pip install -e . 是自安装：

pip 先读取 pyproject.toml，把当前项目打包成标准的 Python 软件包；

pip 会像安装任何第三包那样，安装刚刚打包好的软件包 (含依赖)．

当前项目的源代码也会被打包进去 (比如 main.py 也被放进了 site-packages 目录下)；

这样做的好处是：我们的源代码在导入本项目别的代码时，可以不用相对导入 (如 from . import foo)，而用绝对导入 (如 import AAA.foo)，这样写会与项目使用者写法保持一致，语义更清晰；

但这样就存在两份一样的源代码，会引入修改同步问题．此时使用 -e 参数 (编辑模式)，site-packages 目录下的源代码将变成链接文件，指向项目源代码．

uv run 已经自动在运行脚本之前帮我们自安装好啦，不用操心．

Python 传说
在 Python 官方没有标准规定 pyproject.toml 文件之前，若想让别人复现这个环境，需使用
Terminal window
1
pip freeze > requirements.txt
把所有包导出到 requirements.txt：
requirements.txt
1
flask==3.1.3
2
blinker==1.9.0
3
click==8.3.1
4
itsdangerous==2.2.0
5
jinja2==3.1.6
6
markupsafe==3.0.3
7
werkzeug==3.1.6
但 requirements.txt 混合了所有的直接或间接依赖，很难维护 (比如删除 flask 之后，剩余的间接依赖仍被保留，因为 requirements.txt 并不包含依赖关系的信息)．

项目结构#

flat layout：

1
AAA
2
├─AAA
3
│  ├─app.py
4
│  ├─bar.py
5
│  └─foo.py
6
├─...
7
├─docs
8
├─...
9
├─tests
10
├─...
11
├─pyproject.toml
12
├─README.md
13
└─...

src layout：

1
AAA
2
├─docs
3
├─...
4
├─src
5
│  └─AAA
6
│     ├─app.py
7
│     ├─bar.py
8
│     └─foo.py
9
├─tests
10
├─...
11
├─pyproject.toml
12
├─README.md
13
└─...

为什么要套娃
如果没有套一层，项目打包并解压到 site-packages 后，根目录的源代码会裸露在 site-packages 里，此时会有导入污染的问题：
1
import app, bar, foo # 万一同时有 AAA.app 和 BBB.app 怎么办？
如果套了一层，就不会有这个污染问题：
1
import AAA.app
2
from AAA import app, bar, foo

打包#

认识 .whl
当我们使用 pip，uv，poetry 这些工具安装软件包时，都会在 PyPI 下载相应的 .whl 文件 (如 flask-3.1.3-py3-none-any.whl)，其本质就是压缩包．
所谓的 pip install，就是将 .whl 压缩包解压到 site-packages 目录里
Terminal window
1
└─.venv
2
    ├─Lib
3
    │  └─site-packages
4
    │      ├─__pycache__
5
    │      ├─...
6
    │      ├─AAA
7
    │      │  ├─__pycache__
8
    │      │  ├─module
9
    │      │  │  ├─cat.py
10
    │      │  │  ├─dog.py
11
    │      │  │  └─...
12
    │      │  ├─app.py
13
    │      │  ├─bar.py
14
    │      │  ├─foo.py
15
    │      │  └─...
16
    │      ├─AAA-0.1.0.dist-info
17
    │      │  └─...
18
    │      ├─...
19
    │      ├─flask
20
    │      │  ├─__pycache__
21
    │      │  └─...
22
    │      ├─flask-3.1.3.dist-info
23
    │      │  └─...
24
    │      └─...
25
    └─Scripts
flask 目录存放着该库的所有源代码，此时可以使用 import flask.app 来导入 app.py 文件．

flask-3.1.3.dist-info 目录里的 METADATA 文件由 pyproject.toml 生成，记录了所需依赖．

Python 构建系统
.whl 文件如何生成？
Python 的构建系统分为前端 (命令行工具，官方推荐工具为 build) 和后端 (把项目代码打包成 .whl 文件，默认使用 setuptools 作为后端)．由于 PEP 517 规范把前后端之间的交互接口定义得十分清晰，社区涌现了许多第三方实现，如 flit，hatchling，uv，poetry，PDM 等，它们都可以作为前端和后端，可以自由组合．
下面我们使用 build 作为前端，hatchling 作为后端．

安装 build：

1
pip install build

根据 hatchling 的要求，配置 pyproject.toml：

1
[project]
2
name = "AAA"
3
version = "0.1.0"
4
description = "AAAAAA"
5
readme = "README.md"
6
requires-python = ">=3.12"
7
dependencies = [
8
    "flask>=3.1.3",
9
]
10

11
[build-system]
12
requires = ["hatchling"]
13
build-backend = "hatchling.build"
14

15
[tool.hatch.build.targets.wheel]
16
packages = ["src/AAA"]

现在可以打包了：

1
PS C:\Users\Shy_Vector\AAA> python -m build
2
* Creating isolated environment: venv+pip...
3
* Installing packages in isolated environment:
4
  - hatchling
5
* Getting build dependencies for sdist...
6
* Building sdist...
7
* Building wheel from sdist
8
* Creating isolated environment: venv+pip...
9
* Installing packages in isolated environment:
10
  - hatchling
11
* Getting build dependencies for wheel...
12
* Building wheel...
13
Successfully built AAA-0.1.0.tar.gz and AAA-0.1.0-py3-none-any.whl

也可以使用 uv 作为前端：uv build，比 build 快．

打包出来的 .whl 和 .tar.gz 存放在项目的 dist 目录里：

1
PS C:\Users\Shy_Vector\AAA> unzip -l ./dist/AAA-0.1.0-py3-none-any.whl
2
Archive:  ./dist/AAA-0.1.0-py3-none-any.whl
3
  Length      Date    Time    Name
4
---------  ---------- -----   ----
5
      162  2020/02/02 00:00   AAA/main.py
6
      128  2020/02/02 00:00   AAA-0.1.0.dist-info/METADATA
7
       87  2020/02/02 00:00   AAA-0.1.0.dist-info/WHEEL
8
      280  2020/02/02 00:00   AAA-0.1.0.dist-info/RECORD
9
---------                     -------
10
      657                     4 files

__init__.py

hatchling 默认支持 src layout．

只需要添加空文件 __init__.py 让 hatchling 认为其所在的目录 AAA 可打包．

1
[project]
2
name = "AAA"
3
version = "0.1.0"
4
description = "AAAAAA"
5
readme = "README.md"
6
requires-python = ">=3.12"
7
dependencies = [
8
    "flask>=3.1.3",
9
]
10

11
[build-system]
12
requires = ["hatchling"]
13
build-backend = "hatchling.build"
14

15
[tool.hatch.build.targets.wheel]
16
packages = ["src/AAA"]

1
PS C:\Users\Shy_Vector\AAA> python -m build
2
PS C:\Users\Shy_Vector\AAA> unzip -l ./dist/AAA-0.1.0-py3-none-any.whl
3
Archive:  ./dist/AAA-0.1.0-py3-none-any.whl
4
  Length      Date    Time    Name
5
---------  ---------- -----   ----
6
        0  2020/02/02 00:00   AAA/__init__.py
7
      162  2020/02/02 00:00   AAA/main.py
8
      128  2020/02/02 00:00   AAA-0.1.0.dist-info/METADATA
9
       87  2020/02/02 00:00   AAA-0.1.0.dist-info/WHEEL
10
      354  2020/02/02 00:00   AAA-0.1.0.dist-info/RECORD
11
---------                     -------
12
      731                     5 files

可以 pip install 或者 uv add 将 .whl 文件解压至 .venv\\Lib\\site-packages，实现软件包的安装．