Python 操作与命令

本文是命令速查，成对双花括号中的内容是待替换参数，不是可直接复制的 shell 语法。先确认已安装工具的版本与项目约定；uv、Poetry 为第三方工具。以下 Poetry 的 sync 工作流以 2.x 为前提，旧版请查对应版本帮助。

选择解释器与创建虚拟环境

先选 Python 解释器，再创建项目环境；uv python 管理版本，uv venv 创建环境，命令工具安装放到运行工具场景。

py（Windows） · 用于 Windows 的 Python 启动器，可运行指定的 Python 版本

另请参阅：python。 更多信息：https://docs.python.org/using/windows.html#python-launcher-for-windows。

• 启动一个 REPL（交互式命令行），可以选择使用 python 支持的参数（如 -c、-m 等）：

py {{python 参数}}

• 执行指定的 Python 文件：

py {{路径/到/文件.py}}

• 运行指定版本的 Python. 若缺少该版本且设置了 PYLAUNCHER_ALLOW_INSTALL 环境变量，则通过 Microsoft Store 或 Winget 自动安装：

py {{-2|-3.7|...}}

• 列出已安装的 Python 版本：

py --list

python · Python 语言解释器

更多信息：https://docs.python.org/using/cmdline.html。

• 启动 REPL（交互式 shell）：

python

• 执行特定 Python 文件：

python {{路径/到/文件.py}}

• 执行特定 Python 文件后进入 REPL：

python -i {{路径/到/文件.py}}

• 执行 Python 表达式：

python -c "{{表达式}}"

• 运行特定模块的脚本：

python -m {{模块}} {{参数}}

• 使用 pip 安装包：

python -m pip install {{包}}

• 互动调试 Python 脚本：

python -m pdb {{路径/到/文件.py}}

• 仅绑定回环地址，在端口 8000 提供当前目录文件（本地临时查看用）：

python -m http.server --bind 127.0.0.1

uv python · 管理 Python 版本和安装

更多信息：https://docs.astral.sh/uv/reference/cli/#uv-python。

• 列出所有可用的 Python 安装：

uv python list

• 安装某个版本的 Python：

uv python install {{版本}}

• 卸载某个版本的 Python：

uv python uninstall {{版本}}

• 搜索某个版本的 Python 安装：

uv python find {{版本}}

• 锁定当前项目使用特定版本的 Python：

uv python pin {{版本}}

• 显示 uv Python 安装目录：

uv python dir

安装并固定解释器后，继续 创建虚拟环境；临时运行工具见 uv tool。

uv venv · 创建一个用于安装软件包的隔离 Python 环境

更多信息：https://docs.astral.sh/uv/reference/cli/#uv-venv。

• 在默认位置创建虚拟环境（.venv）：

uv venv

• 在特定路径下创建一个虚拟环境：

uv venv {{路径/到/虚拟环境}}

• 使用特定的 Python 版本创建：

uv venv --python {{3.12}}

• 使用自定义提示词前缀进行创建：

uv venv --prompt {{我的_项目}}

• 创建并允许覆盖现有环境：

uv venv --allow-existing {{虚拟环境_名称}}

• 创建指定解释器的虚拟环境:

uv venv --python {{3.12}} {{.venv}}

创建项目并声明依赖

uv 的项目入口保留 init/remove/run 等常用操作，详细依赖选项查 uv add；Poetry 工作流作为另一条项目路径。

uv · 一个快速的 Python 软件包和项目管理器

此命令也有关于其子命令的文件，例如：tool 和 python。 更多信息：https://docs.astral.sh/uv/reference/cli/。

• 在当前目录中创建一个新的 Python 项目：

uv init

• 在具有指定名称的目录中创建一个新的 Python 项目：

uv init {{项目名称}}

• 向项目中添加一个新的软件包：

uv add {{软件包}}

• 从项目中移除一个软件包：

uv remove {{软件包}}

• 在项目的环境中运行一个脚本：

uv run {{路径/到/脚本.py}}

• 在项目的环境中运行一个命令：

uv run {{命令}}

• 从 pyproject.toml 更新项目的环境：

参见 uv sync。

• 为项目的依赖项创建一个锁定文件：

uv lock

项目操作顺序： 用上面的 uv init 创建项目，依赖声明及开发组见 uv add，移除依赖用 uv remove；随后检查 锁文件与环境同步。

uv add · 将包依赖添加到 pyproject.toml 文件

包的详细解释，请参考 https://peps.python.org/pep-0508/。 更多信息：https://docs.astral.sh/uv/reference/cli/#uv-add。

• 添加一个包（最新版本）：

uv add {{包名}}

• 添加多个包：

uv add {{包1 包2 ...}}

• 添加一个包，并限制其版本：

uv add "{{包名>=1.2.3}}"

• 将包添加到可选依赖组，并在发布时包含在内：

uv add --optional {{可选依赖组}} {{包1 包2 ...}}

• 将包添加到本地依赖组，发布时不会包含在内：

uv add --group {{本地依赖组}} {{package1 package2 ...}}

• 将包添加到 dev 本地依赖组，作为 --group dev 的简写：

uv add --dev {{包1 包2 ...}}

• 添加包，并设定为可编辑的：

uv add --editable {{路径/到/包}}/

• 安装包时，启用一个附加功能（可以多次提供该参数）：

uv add {{包名}} --extra {{附加_功能}}

poetry project workflow · 创建 Python 包并更新依赖声明

• 创建包目录:

poetry new {{project}}

• 添加运行依赖:

poetry add {{httpx}}

• 添加测试依赖组:

poetry add --group test {{pytest}}

• 移除依赖并更新环境:

poetry remove {{httpx}}

检查锁文件并同步环境

区分更新依赖声明、更新锁文件和同步环境；锁文件一致性检查与细分依赖组的同步示例分别保留。

uv lock workflow · 维护锁文件并重现项目环境

• 检查锁文件是否与项目一致:

uv lock --check

• 依据锁文件同步环境，过期时失败；移除多余包:

uv sync --locked

• 仅升级指定锁定依赖:

uv lock --upgrade-package {{httpx}}

• 导出锁定依赖到文件:

uv export --locked --format requirements-txt --output-file {{requirements.txt}}

uv sync · 更新项目环境，来匹配锁文件 (lockfile)

更多信息：https://docs.astral.sh/uv/reference/cli/#uv-sync。

• 将项目环境与锁文件同步：

uv sync

• 同步，并且包含所有的可选依赖：

uv sync --all-extras

• 同步，包含特定的可选依赖：

uv sync --extra {{可选依赖_名称}}

• 仅同步开发环境依赖：

uv sync --only-dev

• 同步，但排除开发环境依赖：

uv sync --no-dev

• 同步特定的依赖组：

uv sync --group {{依赖组_名称}}

• 检查环境是否已经同步（不会做出更改）：

uv sync --check

• 预览同步会做出的更改，但是不执行：

uv sync --dry-run

poetry lock workflow · 检查锁文件并同步 Poetry 环境

• 验证项目与锁文件一致:

poetry check --lock

• 更新锁文件并保留已锁定版本:

poetry lock

• 按锁文件同步并移除多余包:

poetry sync

• 升级指定依赖并更新锁文件与环境:

poetry update {{httpx}}

运行隔离工具、项目代码与构建包

uv tool 面向独立命令工具，Poetry run/build 面向项目运行和分发包；固定工具版本的示例并入 uv tool。

uv tool · 安装和运行由 Python 软件包提供的命令

更多信息：https://docs.astral.sh/uv/reference/cli/#uv-tool。

• 在临时隔离环境中安装所需包并运行命令（不加入项目依赖或持久工具列表，仍可能联网下载）：

uv tool run {{命令}}

• 在用户工具环境中安装一个 Python 命令工具：

uv tool install {{软件包}}

• 升级已安装的 Python 软件包：

uv tool upgrade {{软件包}}

• 卸载一个 Python 软件包：

uv tool uninstall {{软件包}}

• 列出已安装的用户命令工具：

uv tool list

• 临时安装并运行固定版本工具:

uv tool run --from {{ruff==0.11.0}} ruff check {{src}}

poetry run and build · 在项目环境中运行代码并构建分发包

• 选择项目解释器:

poetry env use {{python3.12}}

• 查看环境路径:

poetry env info --path

• 运行已安装的测试工具:

poetry run pytest {{tests}}

• 构建 wheel 与源码分发包:

poetry build

导出与交换依赖声明

导出不同依赖格式时先确定需要生产依赖、开发组还是可选附加项。

uv export · 将项目的锁文件 (lockfile) 导出为其它格式

更多信息：https://docs.astral.sh/uv/reference/cli/#uv-export。

• 将依赖项导出到 requirements.txt 文件：

uv export --format requirements-txt {{[-o|--output-file]}} {{requirements.txt}}

• 将依赖项导出为 pylock.toml 格式：

uv export --format pylock.toml

• 仅导出生产环境的依赖项（不包括开发环境依赖）：

uv export --no-dev

• 导出默认依赖，并包含指定可选附加项（extra，不是依赖组）：

uv export --extra {{附加项_名称}}

• 导出，并包含所有可选依赖：

uv export --all-extras

• 导出，并包含特定的依赖组：

uv export --group {{依赖组_名称}}

• 导出，但不包含哈希值：

uv export --no-hashes

• 为工作区的特定程序包，导出依赖项：

uv export --package {{程序_包名}}

通过 pip 接口安装与检查环境包

pip/uv pip 的安装、卸载与冻结示例保留；它们与前面修改项目依赖声明的工作流分别查阅。

pip · Python 主流的包安装管理工具

更多信息：https://pip.pypa.io/en/stable/cli/pip/。

• 安装包（通过 pip install 查看更多安装示例）：

参见 pip install。

• 安装包到用户目录而不是系统范围的默认位置：

pip install --user {{包名}}

• 升级包：

pip install {{[-U|--upgrade]}} {{包名}}

• 卸载包：

pip uninstall {{包名}}

• 将已安装的包以 Requirements 的格式保存文件中：

pip freeze > {{requirements.txt}}

• 查看包的详细信息：

pip show {{包名}}

• 通过依赖文件（如 requirements.txt）来进行安装：

参见 pip install。

pip install · 用于安装 Python 包

更多信息：https://pip.pypa.io/en/stable/cli/pip_install/。

• 安装包：

pip install {{包名}}

• 安装指定版本的包：

pip install {{包名}}=={{版本号}}

• 通过指定的依赖文件安装（通常文件名是 requirements.txt）：

pip install {{[-r|--requirement]}} {{requirements.txt}}

• 直接安装 URL 指向或本地保存的源码存档、wheel：

python -m pip install "{{URL或存档文件路径}}"

• 从额外页面或目录查找候选分发包，并安装指定包（--find-links 本身不是安装目标）：

python -m pip install --find-links "{{页面URL或目录}}" {{包名}}

• 在本地的项目路径下以开发模式（editable）安装（通常是读取 pyproject.toml 或 setup.py 文件）：

pip install {{[-e|--editable]}} .

uv pip · 提供类似 pip 的命令，用于安装、卸载和管理程序包

更多信息：https://docs.astral.sh/uv/reference/cli/#uv-pip。

• 安装一个包：

uv pip install {{包名}}

• 根据程序包依赖需求文件，安装程序包：

uv pip install {{[-r|--requirements]}} {{requirements.txt}}

• 安装特定版本的一个包：

uv pip install {{包名==1.2.3}}

• 卸载一个包：

uv pip uninstall {{包名}}

• 将安装的包列表，保存到文件：

uv pip freeze > {{requirements.txt}}

• 列出安装的包：

uv pip list

• 展示关于某个已安装包的信息：

uv pip show {{包名}}

• 将环境与程序包依赖需求文件进行同步（将会安装/卸载程序包，来完全匹配该文件）：

uv pip sync {{requirements.txt}}

---

示例整理自 tldr-pages，作者为 tldr-pages team and contributors，遵循 CC BY 4.0。