skills.rest
Arasz
AraszCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

python-global-tool-management

Installs user-scoped Python CLI tools under PEP 668 using uv, pipx, or virtualenvs.

2|Updated Aug 2, 2026
Search Tags:#python#uv#homebrew#cli tools#virtualenv#pipx#pep 668
One-click install
npx skills add https://github.com/Arasz/ai-raccoon --skill python-global-tool-management-arasz
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: python-global-tool-management
Source: https://github.com/Arasz/ai-raccoon/tree/main/.ai-badger/skills/learned/devops/python-global-tool-management
Command: npx skills add https://github.com/Arasz/ai-raccoon --skill python-global-tool-management-arasz

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Modern Python distributions on macOS and Linux enforce PEP 668, which blocks pip install into system or Homebrew site-packages with an externally-managed-environment error. This Skill guides the safe installation of global Python CLI tools without corrupting system environments. ## Core Features & Use Cases - Tool Manager Hierarchy: Recommends uv tool install as the default, with pipx as a fallback and custom user virtualenvs for advanced cases. - Python Version Compatibility Handling: Explains how to work around missing binary wheels on new host Python versions (e.g., 3.14) by pinning an older interpreter such as 3.11. - Anti-Pattern Rejection: Explicitly blocks dangerous approaches like pip install --user and pip --break-system-packages that corrupt Homebrew site-packages. - Use Case: You run pip install ruff on macOS and hit error: externally-managed-environment. This Skill directs you to uv tool install ruff, which creates an isolated environment and symlinks the binary into ~/.local/bin. ## Quick Start Ask the assistant to install a global Python CLI tool like ruff or black on your machine without triggering PEP 668 errors.

Frequently Asked Questions about python-global-tool-management

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I fix the externally-managed-environment error when running pip install?▼

The externally-managed-environment error comes from PEP 668, which blocks pip installs into system or Homebrew Python. Use `uv tool install <package>` or `pipx install <package>` instead, which create isolated environments for CLI tools.

uv tool vs pipx for installing Python CLI tools?▼

uv tool is the preferred default because it automatically downloads a compatible standalone CPython build when the host Python lacks binary wheels for dependencies. pipx works well too but defaults to the host interpreter, which can fail on very new Python versions.

Why does pipx install fail on Python 3.14?▼

pipx uses the host Homebrew Python by default, and packages with C-extension dependencies may lack pre-built wheels for Python 3.14, causing build failures. Fix it by pinning an older interpreter: `pipx install --python python3.11 <package>`.

Is it safe to use pip install --break-system-packages?▼

No, `pip --break-system-packages` is dangerous because it writes into Homebrew-managed site-packages, which can corrupt your Python installation and break after a `brew upgrade`. Always use an isolated tool manager like uv or pipx instead.

How do I make uv or pipx installed tools available in my terminal?▼

Add `~/.local/bin` to your PATH in `~/.zshrc` or `~/.bashrc` with `export PATH="$HOME/.local/bin:$PATH"`. Place it ahead of `/opt/homebrew/bin` so user-installed tools take precedence over Homebrew binaries.

Related Skills

Explore More Software Engineering Skills→
evolv3aievolv3ai
3

admin-unix

Administer macOS and Linux systems via shell commands and JSON profiles.

Community
Intermediate
westonwrzwestonwrz

ruff

Configure, tune, and operate Ruff for Python linting and formatting.

Community
Advanced
EngineerWithAIEngineerWithAI
4

uv-package-manager

Manage Python dependencies and virtual environments with the uv package manager.

Official
Intermediate
JetBrainsJetBrains
302

skillshare-devcontainer

Run skillshare and CLI tasks inside a Linux devcontainer.

Official
Intermediate