---
# SPDX-License-Identifier: Apache-2.0
name: uv-pip-install
description: Install and manage Python packages using uv pip. Use when a Python import fails with ModuleNotFoundError, user asks to install a package, or a script requires a missing dependency.
---
# uv-pip-install
Install and manage Python packages in the uv-managed virtual environment.
## Quick start
```bash
# Install a package
uv pip install requests
# Install multiple packages
uv pip install pandas numpy matplotlib
# Install with extras
uv pip install httpx[http2]
# Check if a package is installed
uv pip show python-docx
# List all installed packages
uv pip list
# Upgrade a package
uv pip install --upgrade requests
```
## When to use
- Python import fails with `ModuleNotFoundError`
- User asks to install a Python package
- A script requires dependencies that are not installed
## Common module-to-package mappings
| Import name | Package name |
|-------------|--------------|
| cv2 | opencv-python |
| PIL | pillow |
| sklearn | scikit-learn |
| yaml | pyyaml |
| docx | python-docx |
| pptx | python-pptx |
| bs4 | beautifulsoup4 |
| dotenv | python-dotenv |
| attr | attrs |
| dateutil | python-dateutil |
| gi | pygobject |
| magic | python-magic |
| serial | pyserial |
| usb | pyusb |
| Crypto | pycryptodome |
| jwt | pyjwt |
| jose | python-jose |
| lxml | lxml |
| wx | wxPython |
| gi | PyGObject |
| skimage | scikit-image |
| fitz | PyMuPDF |
| cv | opencv-python |
| telegram | python-telegram-bot |
| discord | discord.py |
| flask_cors | flask-cors |
| sqlalchemy | SQLAlchemy |
| alembic | alembic |
| pymongo | pymongo |
| redis | redis |
| celery | celery |
| fastapi | fastapi |
| uvicorn | uvicorn |
| httpx | httpx |
| aiohttp | aiohttp |
| websockets | websockets |
| jinja2 | Jinja2 |
| markdownify | markdownify |
## Workflow
1. If an import error occurs, extract the module name.
2. Map module name to package name if different (see table above).
3. Check if already installed: `uv pip show <package>`
4. If not installed: `uv pip install <package>`
## Troubleshooting
### Common issues
| Problem | Solution |
|---------|----------|
| `uv: command not found` | Install uv: `curl -LsSf https://astral.sh/uv/install.sh \| sh` |
| Package installs but import still fails | Check you're in the correct venv: `which python` |
| Version conflict | Pin version: `uv pip install package==1.2.3` |
| Build fails (C extension) | Install system deps: `brew install pkg-config` (macOS) |
| SSL certificate error | `uv pip install --trusted-host pypi.org package` |
## Notes
- Always run from the project directory so the correct `.venv` is used.
- Use `uv pip` (not plain `pip`) to ensure packages go into the uv-managed environment.
- For packages with C extensions, ensure build tools are installed (`xcode-select --install` on macOS).