pip
Use this skill for Python dependency management with safe defaults and reproducible results.
Scope
- - Create and maintain project-local virtual environments
- Install, upgrade, uninstall, and inspect Python packages
- Manage
requirements.txt and lock-like pinned outputs (pip freeze) - Troubleshoot common pip failures (
externally-managed-environment, resolver conflicts, wheel/build failures)
Safety Defaults
- - Prefer isolated installs:
- project:
python3 -m venv .venv
- app CLI:
pipx (if available)
- - Avoid global installs unless user explicitly asks.
- Prefer
python3 -m pip ... instead of bare pip to avoid interpreter mismatch. - Never run unknown
setup.py or arbitrary install scripts without explicit user approval.
Fast Path
CODEBLOCK0
Common Operations
CODEBLOCK1
Reproducible Dependency Flows
CODEBLOCK2
Troubleshooting
- -
externally-managed-environment:
- Use a venv (
python3 -m venv .venv) and retry inside it.
- If user asked for app CLI install, prefer
pipx install <tool>.
- -
No matching distribution found:
- Check Python version compatibility.
- Check package name/version typo.
- Try
python3 -m pip index versions <pkg> when available.
- Upgrade build tooling:
python3 -m pip install -U pip setuptools wheel
- Install system headers/toolchain if needed, then retry.
Helper Script
Use the bundled helper for repeatable flows:
CODEBLOCK3
Decision Rules
- - If task is project dependencies: use venv + pip.
- If task is standalone CLI tool install for a user: suggest
pipx first. - If system policy blocks global installs: stay in venv and explain why.
pip
使用此技能进行Python依赖管理，采用安全默认配置并确保结果可复现。
适用范围
- - 创建和维护项目本地虚拟环境
- 安装、升级、卸载和检查Python包
- 管理requirements.txt及类似锁定版本的固定输出（pip freeze）
- 排查常见pip故障（externally-managed-environment、解析器冲突、wheel/构建失败）
安全默认配置
- 项目：python3 -m venv .venv
- 应用CLI：pipx（如可用）
- - 除非用户明确要求，否则避免全局安装。
- 优先使用python3 -m pip ...而非裸pip，以避免解释器不匹配。
- 未经用户明确批准，绝不运行未知的setup.py或任意安装脚本。
快速路径
bash
每个项目初始化一次虚拟环境
python3 -m venv .venv
. .venv/bin/activate
python3 -m pip install --upgrade pip
安装依赖
python3 -m pip install -r requirements.txt
固定精确版本
python3 -m pip freeze > requirements.txt
常用操作
bash
安装一个或多个包
python3 -m pip install requests pydantic
升级特定包
python3 -m pip install --upgrade requests
卸载包
python3 -m pip uninstall -y requests
查看包详情
python3 -m pip show requests
列出过时包
python3 -m pip list --outdated
可复现的依赖流程
bash
从锁定文件安装
python3 -m pip install -r requirements.txt
生成固定版本快照
python3 -m pip freeze > requirements.txt
导出JSON元数据用于自动化
python3 -m pip list --format=json
故障排查
- - externally-managed-environment：
- 使用虚拟环境（python3 -m venv .venv）并在其中重试。
- 如果用户要求安装应用CLI，优先使用pipx install
。
- - No matching distribution found：
- 检查Python版本兼容性。
- 检查包名/版本拼写错误。
- 如可用，尝试python3 -m pip index versions 。
- 升级构建工具：python3 -m pip install -U pip setuptools wheel
- 如有需要，安装系统头文件/工具链，然后重试。
辅助脚本
使用内置辅助脚本实现可重复流程：
bash
{baseDir}/scripts/pip-safe.sh detect
{baseDir}/scripts/pip-safe.sh ensure-venv .venv
{baseDir}/scripts/pip-safe.sh install --venv .venv -- requests pydantic
{baseDir}/scripts/pip-safe.sh requirements --venv .venv requirements.txt
{baseDir}/scripts/pip-safe.sh freeze --venv .venv > requirements.txt
决策规则
- - 如果任务是项目依赖管理：使用虚拟环境 + pip。
- 如果任务是为用户安装独立CLI工具：优先建议使用pipx。
- 如果系统策略阻止全局安装：保持在虚拟环境中，并解释原因。
