所谓“管理 python 开发项目”,内容包括管理虚拟环境、安排项目的文件夹结构、安装/卸载第三方库;目标是尽量保证版本锁定、不同平台的行为一致、项目代码的更新即时反映到开发和测试环境中。
“回”字有四样写法,你知道么?
本文归纳整理了使用 poetry, uv, conda, virtualenv(wrapper) 四种包管理工具,以及不使用额外工具来管理 python 开发项目的方法。
所谓“管理 python 开发项目”,内容包括管理虚拟环境、安排项目的文件夹结构、安装/卸载第三方库;目标是尽量保证版本锁定、不同平台的行为一致、项目代码的更新即时反映到开发和测试环境中。
四种工具:
| 工具 | 口碑 | 虚拟环境 | 包管理器的仓库 |
|---|---|---|---|
poetry | 体验接近 Node.js 的 npm | 可设为每个项目独立 | PyPI |
uv | Rust 写成、快、名气大 | 默认每个项目独立 | PyPI |
conda | 以前在科研界非常流行 | 集中在 $CONDA_PREFIX | conda, conda-pypi |
virtualenv | 尽量贴近原版 | 集中在 $WORKON_HOME | PyPI |
了解不使用额外工具的管理方法,就像开手动档汽车一样:一方面更容易让人对 python 运行时究竟在干什么保持清醒;另一方面大语言模型是不需要太多脚手架的,以后这种极简风格的项目有可能越来越常见。
建议阅读方法:
- 二级标题
<h2/>:管理 python 开发项目的各个步骤,按顺序阅读每一节 - 三级标题
<h3/>:每个工具对二级标题的任务是如何操作的,根据所用工具多选一
每台设备上的一次性准备工作
poetry
poetry 的下载地址:https://python-poetry.org/docs/#installation
安装完成之后,查看 poetry 现有设置: poetry config --list
我习惯把虚拟环境的存放位置改成每个项目内部:poetry config virtualenvs.in-project true
以前是靠用户自己下载安装 python 可执行文件,具体方法见《python 可执行文件》一节。
poetry python 系列命令目前处于实验阶段,将来接口可能变化。
poetry python list 列出的是本机已经安装的 python 版本。
poetry python install VERSION 可以通过 poetry 安装本机没有的特定 python 版本。
uv
根据官方指南下载和安装 uv:https://docs.astral.sh/uv/getting-started/installation/
uv 安装时不需要本机存在 python 的可执行文件。将来在每一个项目里可以随便指定需要的 python 版本,uv 会先在本地搜索,找不到就自己下载安装。
uv python list 命令可以列出所有可用的 python 版本,包括本机已存在的,和 uv 可以下载的。
uv python install VERSION 命令可以通过 uv 安装特定版本的 python,不写 VERSION 则默认为最新版本。
conda
已经不玩 conda 很多年,为了这篇博客回到它官网看了半天,各种产品依然让人头大,而且文档不好找。能满足我们要求的最简产品是 miniconda。
Miniconda 的下载地址:https://www.anaconda.com/docs/getting-started/installation
conda 也不需要本机预先存在 python 的可执行文件。但是由于 conda 里的 python 版本和虚拟环境强绑定,所以在《虚拟环境》一节介绍。
python 可执行文件
纯手动管理和 virtualenv(wrapper) 都需要自己下载和安装 python 的可执行文件,方法在《在 Windows 10 上配置 python 开发环境》。
在没有管理员权限的 Linux 系统上,需要自己编译 python,方法在《非管理员权限安装 Python》
virtualenv(wrapper)
在本机已经存在 python 可执行文件的前提下,用系统默认的 python 安装
- Linux:
pip install virtualenvwrapper - CMD on Windows:
pip install virtualenvwrapper-win - PowerShell on Windows:
pip install virtualenvwrapper-powershell
然后在 shell 的启动脚本里(一般是 ~/.bashrc)添加如下几行:
export WORKON_HOME=$HOME/.virtualenvs
export PROJECT_HOME=$HOME/Devel
source /usr/local/bin/virtualenvwrapper.sh
以下各节,每次开始一个新项目都要执行一遍
初始化项目
poetry
poetry init 可以在当前文件夹里初始化一个 python 项目。
poetry new PROJECT 可以在当前文件夹内新建一个名为 PROJECT 的文件夹,然后在里面初始化项目。因为我喜欢从 GitHub 上克隆空项目来避免从本地设置 remote,所以一般用不到这个。
两个命令都会问你一堆选择题,根据提示一步步回答,结束之后就得到一个结构完整的 python 项目文件夹。
uv
uv init 可以在当前文件夹里初始化一个 python 项目所需要的各种文件。项目结构默认为 src/ 型。
这个命令还可以在后面加宾语,会变成在当前文件夹内新建一个名为宾语的文件夹,然后在里面初始化项目,相当于 poetry new PROJECT。同样因为我喜欢从 GitHub 上克隆空项目来避免从本地设置 remote,所以一般用不到这个。
不像 poetry 一样每次问一堆问题,uv 直接按默认值给你初始化一个项目。如果对默认值不满意,可以用 --app、--package、--lib 指定项目类型,具体见 uv init --help。
conda
说了一些黑 conda 使用者的话
项目文件夹按下面《不使用额外工具》一节的办法手动建。
virtualenv(wrapper)
virtualenvwrapper 只管虚拟环境,不管项目结构,项目文件夹同样按下面《不使用额外工具》一节的办法手动建。
不使用额外工具
在项目文件夹下,手动建立如下结构的目录( src/ 型):
PROJECT/
├── pyproject.toml
├── README.md
├── .gitignore
├── src/
│ └── PACKAGE_NAME/
│ └── __init__.py
└── tests/
└── test_example.py
src/ 型的好处是:必须把项目装进虚拟环境才能 import,测试时跑的是和别人装到的一样的代码,不会误用当前文件夹里的文件。
.gitignore 里至少写上 .venv/ 和 __pycache__/,也可以直接套 GitHub 上的模板。
最小的 pyproject.toml 如下,PACKAGE_NAME 要和 src/ 里的文件夹名一致:
[build-system]
requires = ["setuptools>=64"]
build-backend = "setuptools.build_meta"
[project]
name = "PACKAGE_NAME"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = []
[dependency-groups]
dev = ["pytest","jupyter"]
虚拟环境
poetry
如果想指定虚拟环境使用的 python 版本,先用 poetry env use 3.12(也可以写 python 可执行文件的完整路径),再 poetry install。
在 virtualenvs.in-project 设为 true 的前提下,poetry install 或 poetry sync 会在项目文件夹里自动建好 .venv,不需要额外操作。
不同平台上,激活虚拟环境的命令不同:
- Bash on Linux:
eval $(poetry env activate) - PowerShell on Windows:
Invoke-Expression (poetry env activate)
不想激活虚拟环境时,也可以用 poetry run COMMAND 直接在虚拟环境里执行命令,比如 poetry run pytest -v。
uv
uv python pin 3.12 指定 python 版本,会写入 .python-version 文件
uv sync 会在项目文件夹里自动建好 .venv,不需要额外操作。
uv 不提供专门的命令来激活虚拟环境,需要直接运行启动脚本:
- PowerShell on Windows:
.\.venv\Scripts\activate.ps1 - Bash on Linux:
source .venv/bin/activate
conda
默认情况下,所有环境都集中存放在 conda 安装目录的 envs/ 下面。
conda 里的 python 版本和虚拟环境强绑定,所以建环境时就要指定版本:conda create -n ENV_NAME python=3.12
如果是从别人那里接手来的项目,应该存在 environment.yml 文件, conda env create -f environment.yml
conda activate ENV_NAME 激活环境;
conda deactivate 退出环境。
virtualenv(wrapper)
mkvirtualenv ENV_NAME 在 $WORKON_HOME 下建一个虚拟环境,并且立刻启动它。
需要指定 python 版本时,需要提前安装相应的版本,知道其路径,然后 mkvirtualenv -p PATH/TO/PYTHON ENV_NAME。
workon ENV_NAME 激活环境;workon 不带参数时列出所有虚拟环境,相当于 lsvirtualenv
rmvirtualenv ENV_NAME删除环境
不使用额外工具
比较新的 python 已经自带了 venv 模块,不需要第三方库来处理虚拟环境。
如果本机装了多个 python,虚拟环境会绑定到执行命令的那个解释器。进入项目文件夹,在项目根目录建环境:
- Linux:
PATH/TO/PYTHON -m venv .venv - Windows:
py -3.12 -m venv .venv
然后启动环境:Linux 用 source .venv/bin/activate;Windows PowerShell 用 .venv\Scripts\Activate.ps1。启动成功后,命令行提示符前面会出现 (.venv)
安装/移除某个依赖
这一节介绍如何安装、移除某个依赖,以及如何把依赖记录下来,让别人复现同样的环境。
poetry
如果是从别人那里接手来的项目,应该存在 poetry.lock 文件,用 poetry sync 可以复现环境。
poetry add PACKAGE_NAME(==VERSION) 安装依赖,括号锁定版本。
poetry add --group dev PACKAGE_NAME 安装开发阶段用的依赖,比如 pytest, jupyter
poetry remove PACKAGE_NAME 移除某个依赖。
依赖会自动写入 pyproject.toml 和 poetry.lock;别人拉取之后用 poetry sync 复现环境。
手动改了 pyproject.toml 里的依赖之后,运行 poetry lock 更新锁文件。
uv
如果是从别人那里接手来的项目,应该存在 uv.lock 文件,用 uv sync 可以复现环境。
uv add PACKAGE_NAME(==VERSION) 安装依赖,括号锁定版本。
uv add --dev PACKAGE_NAME 安装开发阶段用的依赖,比如 pytest, jupyter
uv remove PACKAGE_NAME 移除某个依赖。
uv add -r requirements.txt 从传统的需求文件导入,uv 自己不需要手动管理依赖,依赖会自动写入 pyproject.toml 和 uv.lock,把 uv.lock 一起提交进 git,别人 uv sync 之后得到完全一样的环境。
项目有 [build-system] 时(--package、--lib 类型),uv sync 会把项目本身以可编辑方式装进 .venv,改了代码不用重装。
uv pip install PACKAGE_NAME 只往虚拟环境里装包,不改项目文件,适合临时试用。(不推荐,将来忘了容易出问题。)
conda
conda install PACKAGE_NAME(=VERSION) 安装依赖,注意只有一个等号。
conda 仓库里没有的包,从 PyPI 装:conda install conda-pypi::PACKAGE_NAME
项目本身以可编辑方式装入:pip install -e .,改了代码不用重装。
conda remove PACKAGE_NAME 移除某个依赖。
conda env update --file environment.yml --prune 导出环境。(Claude 给的方案是 conda env export --from-history > environment.yml)
别人用 conda env create -f environment.yml 复现。
virtualenv(wrapper)
pip install PACKAGE_NAME(==VERSION) 安装依赖,括号锁定版本。
项目本身以可编辑方式装入:pip install -e .,改了代码不用重装。
pip uninstall PACKAGE_NAME 移除,注意 pip 不会顺带移除这个包的依赖。
pip freeze > requirements.txt 导出依赖,pip freeze 会把间接依赖也一起列出来。这个方法有局限性,不是依赖解析器,也不会自动解决不同平台的依赖冲突。而 poetry 和 uv 的 add/remove 会自动计算依赖关系,解决依赖冲突。
别人用 pip install -r requirements.txt 复现。
pip 不负责更新 pyproject.toml,需要自己手动增删 [project].dependencies 的内容。
不使用额外工具
启动虚拟环境之后,在项目根目录运行 pip install -e ".[dev]"。-e 表示可编辑安装:src/ 里的代码一改,虚拟环境里立刻生效;[dev] 会顺便装上 pytest。
其余做法和 virtualenv(wrapper) 一样,只是虚拟环境是项目里的 .venv。
直接依赖也可以手动写进 pyproject.toml 的 dependencies 列表,再 pip install -e . 重新安装;requirements.txt 则作为 pip freeze 导出的完整快照。
pip 不负责更新 pyproject.toml,需要自己手动增删 [project].dependencies 的内容。
下面这节每次干活时都要来一遍:
日常开发
poetry
- 进入项目
cd PATH/TO/PROJECT - 启动虚拟环境
- Bash on Linux:
eval $(poetry env activate) - PowerShell on Windows:
Invoke-Expression (poetry env activate)
- Bash on Linux:
- (如果)从远程合并他人的版本,然后
poetry install或poetry sync(更推荐后者) - 安装新的依赖
poetry add PACKAGE_NAME(==VERSION) - 移除已有依赖
poetry remove PACKAGE_NAME - 干活,修改代码(在 jupyter 中实时执行命令看结果)
- 测试
pytest -v - 收工,退出虚拟环境
deactivate
uv
- 进入项目
cd PATH/TO/PROJECT - 启动虚拟环境
- Bash on Linux:
source .venv/bin/activate - Powershell on Windows:
.venv\Scripts\activate.ps1 - CMD on Windows:
.venv\Scripts\activate.bat
- Bash on Linux:
- (如果)从远程合并他人的版本,然后
uv sync - 安装新的依赖
uv add PACKAGE_NAME(==VERSION) - 移除某个依赖
uv remove PACKAGE_NAME - 干活,修改代码(在 jupyter 中实时执行命令看结果)
- 测试
pytest -v - 收工,退出虚拟环境
deactivate
conda
- 进入项目
cd PATH/TO/PROJECT - 启动虚拟环境
conda activate ENV_NAME - 安装新的依赖
conda install PACKAGE_NAME(==VERSION)- 从 PyPI 安装
conda install conda-pypi::PACKAGE_NAME
- 从 PyPI 安装
- 移除某个依赖
conda remove PACKAGE_NAME - 将新的依赖写入文件
conda env export --from-history > environment.yml - 干活,修改代码(在 jupyter 中实时执行命令看结果)
- 测试
pytest -v - 收工,退出虚拟环境
conda deactivate
virtualenv(wrapper)
- 进入项目
cd PATH/TO/PROJECT - 启动虚拟环境
workon ENV_NAME - 安装新的依赖
pip install PACKAGE_NAME(==VERSION) - 移除某个依赖
pip uninstall PACKAGE_NAME - 将新的依赖写入文件
pip freeze > requirements.txt - 干活,修改代码(在 jupyter 中实时执行命令看结果)
- 测试
pytest -v - 收工,退出虚拟环境
deactivate
不使用额外工具
- 进入项目
cd PATH/TO/PROJECT - 启动虚拟环境
source .venv/bin/activate,命令行提示符会出现(.venv)字样 - 安装新的依赖
pip install PACKAGE_NAME(==VERSION) - 移除某个依赖
pip uninstall PACKAGE_NAME - 将新的依赖写入文件
pip freeze > requirements.txt - 干活,修改代码(在 jupyter 中实时执行命令看结果)
- 测试
pytest -v - 收工,退出虚拟环境
deactivate
“回”字的四种写法:回、囬、𡇌、囘。
其实不止四种:
https://dict.variants.moe.edu.tw/dictView.jsp?ID=7393
评论