## 🔧 Setup & Installation
```bash
# Install UV via prebuilt installer (recommended for Debian/Unix)
curl -s https://astral.sh/uv/install.sh | bash
# Or force install to ~/.local/bin if default fails
curl -LsSf https://astral.sh/uv/install.sh | env UV_INSTALL_DIR="$HOME/.local/bin" sh
# Or install via Cargo (requires Rust toolchain)
cargo install uv
# Alternatively, install via pipx (if already using Python tooling)
pipx install uv
# Or install via pip (system-wide or in venv)
pip install uv
```
### 🛠 Add to PATH (if needed)
```bash
# If uv is not found, make sure ~/.local/bin or ~/.cargo/bin is in your PATH
export PATH="$HOME/.local/bin:$HOME/.cargo/bin:$PATH"
# Make it permanent (for Bash)
echo 'export PATH="$HOME/.local/bin:$HOME/.cargo/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
```
### 🐛 Troubleshooting `uv: command not found`
```bash
# Check if uv was installed
find ~/.local/bin ~/.cargo/bin -type f -name uv
# Run uv directly (bypass PATH)
~/.local/bin/uv --version
~/.cargo/bin/uv --version
# Check if paths are included
echo $PATH | grep -E 'local|cargo'
# Fix PATH temporarily
export PATH="$HOME/.local/bin:$HOME/.cargo/bin:$PATH"
# Fix PATH permanently
echo 'export PATH="$HOME/.local/bin:$HOME/.cargo/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
# Reinstall to ~/.local/bin if needed
curl -LsSf https://astral.sh/uv/install.sh | env UV_INSTALL_DIR="$HOME/.local/bin" sh
```
## 📦 Environment Management
```bash
# Create a virtual environment (replaces `virtualenv`)
uv venv
# Activate the venv (Unix/macOS)
source .venv/bin/activate
# Activate the venv (Windows)
.venv\Scripts\activate
# Run a Python script in the virtualenv without activating it
uv run python app.py
```
## 📥 Installing Packages
```bash
# Install a package (similar to pip install)
uv pip install requests
# Install with extras
yuv pip install 'fastapi[all]'
# Install from requirements.txt
uv pip install -r requirements.txt
```
## 🔒 Lockfile Management
```bash
# Compile requirements.in to a lockfile (like pip-compile)
uv pip compile requirements.in > requirements.txt
# Install from compiled requirements.txt
uv pip install -r requirements.txt
```
## 🧪 PEP 582 (**pypackages** Support)
```bash
# Install packages to __pypackages__ (no virtualenv needed)
uv pip install -p . --use-pep582 requests
# Run using PEP 582 package pathing
uv run python script.py
```
## 🧹 Clean Up
```bash
# Remove virtualenv and all cached data
rm -rf .venv __pypackages__ .uv .cache __pycache__
```
## ⚡ Tips & Extras
* Use `uv venv --python python3.11` to specify Python version
* Use `uv pip list` to see installed packages
* Use `uv run pytest` to run tests inside the venv
---
**🔗 Resources:**
* GitHub: [https://github.com/astral-sh/uv](https://github.com/astral-sh/uv)
* Docs: [https://astral.sh/blog/posts/introducing-uv/](https://astral.sh/blog/posts/introducing-uv/)
* PEP 582: [https://peps.python.org/pep-0582/](https://peps.python.org/pep-0582/)