pi-pip2uv

中文文档

A small pi extension that blocks pip install-style Python dependency changes and tells the agent to use uv with the current project environment instead.

In pi and many other coding-agent workflows, agents may reach for global Python / pip installs when trying to make a script run, instead of respecting the project's local virtual environment. pi-pip2uv acts as a runtime guardrail: it blocks those unmanaged installs and points the agent back to uv and the local .venv workflow. This is especially useful for small scripts and tool projects, where a lightweight runtime check can be more reliable than relying only on skills, AGENTS.md, or prompt instructions.

The guard uses a strict policy: it also blocks .venv/bin/pip install ..., so agents consistently prefer uv for Python dependency changes.

What it blocks

Blocked by default:

• pip install ...
• pip3 install ...
• python -m pip install ...
• uv pip install --system ...
• pipx install ...
• uv tool install ...

Allowed by default:

• uv add ...
• uv pip install ...
• uv sync
• uv run ...
• uvx ...

Install

From npm:

pi install npm:pi-pip2uv

Pin a specific npm version:

pi install npm:pi-pip2uv@0.1.0

From GitHub:

pi install git:github.com/Zbzdr/pi-pip2uv@v0.1.0

Or test from a local checkout:

pi -e ./index.ts

Restart pi or run /reload after changing installed extensions.

Updating

For unpinned npm installs:

pi update npm:pi-pip2uv

or update all pi packages:

pi update --extensions

For pinned npm versions or GitHub tags, install the newer version explicitly:

pi install npm:pi-pip2uv@0.1.1
pi install git:github.com/Zbzdr/pi-pip2uv@v0.1.1

Load order

For best results, load pi-pip2uv before generic permission/prompt extensions. This lets it block disallowed Python dependency changes immediately, while unrelated commands continue to your normal permission system.

For example, with @gotgenes/pi-permission-system, put it after pi-pip2uv in ~/.pi/agent/settings.json:

{
  "packages": [
    "npm:pi-pip2uv",
    "npm:@gotgenes/pi-permission-system"
  ]
}

Project-local installs also run before user/global packages after the project is trusted.

If a permission system loads first

If a permission extension loads before pi-pip2uv, you can allow the pip/uv install patterns in that permission system so they pass through to pi-pip2uv. Keep those allow rules specific to install commands that pi-pip2uv will block; unrelated commands should still be handled by your permission system.

Loading pi-pip2uv before permission prompts is still the cleanest setup when you control package order.

Configuration

Default configuration lives in config.json next to the extension.

When installed globally, trusted projects can override config at:

.pi/extensions/pi-pip2uv/config.json

Environment variable override:

export PI_PIP2UV_CONFIG=/absolute/path/to/config.json

Legacy environment variable PI_PIP_UV_GUARD_CONFIG is also accepted.

Example config:

{
  "enabled": true,
  "blockPipInstall": true,
  "blockUvSystemInstall": true,
  "blockUserWideToolInstall": true,
  "currentVenvPath": ".venv",
  "notify": true,
  "allowedCommandRegexes": [],
  "extraHint": ""
}

allowedCommandRegexes

allowedCommandRegexes is applied per matched dangerous command snippet. Allowing one snippet does not allow later unsafe snippets in the same shell command.

Use allow rules sparingly and make them as specific as possible; they intentionally weaken the guard.

Test

npm test

You can also run:

node self-test.mjs

Security

pi extensions run with your local user permissions. Review extension source before installing third-party packages.

pi-pip2uv is a policy guard, not a sandbox. It intercepts pi bash tool calls and interactive ! / !! user bash commands before execution, but real isolation should come from your OS, container, VM, or sandbox policy.

Acknowledgements

This project was primarily written with pi and GPT-5.5.

License

MIT