Loading
Also from Kynth Studios
Also from Kynth Studios
Also from Kynth Studios
12345678910# UV Python Project Management Guide1112## Table of Contents13- [Introduction](#introduction)14- [Installation](#installation)15- [Managing Python Versions](#managing-python-versions)16- [Project Management](#project-management)17- [Virtual Environment Management](#virtual-environment-management)18- [Package Management](#package-management)19- [Advanced Configuration](#advanced-configuration)20- [Development Workflows](#development-workflows)21- [Best Practices](#best-practices)22- [Security Considerations](#security-considerations)23- [Performance Optimization](#performance-optimization)24- [Troubleshooting](#troubleshooting)25- [Environment Variables](#environment-variables)26- [Tool Integration](#tool-integration)27- [Common Commands Reference](#common-commands-reference)2829## Introduction3031UV is a modern Python package manager and virtual environment tool that offers significant performance improvements over traditional tools like pip and venv. This guide covers how to effectively use UV for Python project management.3233## Installation3435### macOS36```bash37# Using Homebrew38brew install uv3940# Using the installer script41curl -LsSf https://astral.sh/uv/install.sh | sh42```4344### Linux45```bash46# Using the installer script47curl -LsSf https://astral.sh/uv/install.sh | sh48```4950### Windows51```powershell52# Using winget53winget install --id=astral-sh.uv -e5455# Using scoop56scoop install main/uv57```5859## Managing Python Versions6061UV can manage Python installations for you. Here's how to work with Python versions:6263### Installing Python64```bash65# Install latest Python version66uv python install6768# Install specific Python version69uv python install 3.127071# Install multiple versions72uv python install 3.11 3.127374# Install PyPy75uv python install pypy@3.1076```7778### Listing Python Versions79```bash80# List available and installed versions81uv python list8283# Show all versions including other platforms84uv python list --all-versions8586# Only show installed versions87uv python list --only-installed88```8990### Finding Python Executables91```bash92# Find default Python93uv python find9495# Find specific version96uv python find >=3.1197```9899## Project Management100101UV provides robust project management capabilities through its project system.102103### Creating a New Project104```bash105# Create a new project106uv init my-project107cd my-project108109# Or initialize in current directory110mkdir my-project111cd my-project112uv init113```114115This creates:116- `pyproject.toml` - Project configuration and dependencies117- `.python-version` - Python version specification118- `README.md` - Project documentation119- `main.py` - Initial Python file120121### Project Structure122```123my-project/124├── .venv/ # Virtual environment (created on first use)125├── .python-version # Python version specification126├── pyproject.toml # Project configuration127├── uv.lock # Dependency lock file128├── README.md # Project documentation129└── main.py # Main Python file130```131132### Managing Dependencies133134```bash135# Add dependencies136uv add requests137uv add 'flask>=2.0.0'138uv add 'pytest[testing]'139140# Remove dependencies141uv remove requests142143# Update dependencies144uv lock --upgrade-package requests145146# Install all dependencies147uv sync148```149150## Virtual Environment Management151152UV automatically manages virtual environments for projects and can work with existing environments.153154### Creating Virtual Environments155```bash156# Create venv in default location (.venv)157uv venv158159# Create venv with specific name160uv venv my-env161162# Create venv with specific Python version163uv venv --python 3.12164```165166### Working with Virtual Environments167168```bash169# Activate virtual environment170# On Unix/macOS:171source .venv/bin/activate172173# On Windows:174.venv\Scripts\activate175176# On Fish shell:177source .venv/bin/activate.fish178179# Deactivate virtual environment180deactivate181```182183### Using Existing Environments184185UV automatically detects and uses virtual environments in the following order:1861. Active virtual environment (VIRTUAL_ENV)1872. Active Conda environment (CONDA_PREFIX)1883. `.venv` in current or parent directories189190## Package Management191192UV provides both high-level project commands and pip-compatible commands for package management.193194### Project-Based Package Management195```bash196# Add package to project197uv add package-name198199# Remove package from project200uv remove package-name201202# Sync project dependencies203uv sync204205# Update lockfile206uv lock207```208209### Pip-Compatible Commands210```bash211# Install packages212uv pip install package-name213uv pip install -r requirements.txt214215# Install in editable mode216uv pip install -e .217218# Uninstall packages219uv pip uninstall package-name220221# List installed packages222uv pip list223224# Show package info225uv pip show package-name226227# Generate requirements.txt228uv pip freeze > requirements.txt229```230231## Advanced Configuration232233### pyproject.toml Configuration234```toml235[project]236name = "my-project"237version = "0.1.0"238description = "Project description"239readme = "README.md"240requires-python = ">=3.8"241license = { text = "MIT" }242authors = [243 { name = "Your Name", email = "your.email@example.com" }244]245246dependencies = [247 "requests>=2.28.0",248 "flask[async]>=2.0.0",249 "sqlalchemy",250]251252[project.optional-dependencies]253test = ["pytest>=7.0", "pytest-cov"]254dev = ["black", "mypy", "ruff"]255256[tool.uv]257python-version = "3.12"258```259260### UV Configuration Options261```toml262[tool.uv]263# Package index configuration264[[tool.uv.index]]265url = "https://pypi.org/simple"266default = true267268[[tool.uv.index]]269url = "https://test.pypi.org/simple"270secondary = true271272# Build settings273no-binary = ["cryptography", "numpy"]274build-isolation = true275276# Cache settings277cache-dir = "~/.cache/uv"278```279280### Environment-Specific Settings281```toml282[tool.uv.env]283development = { extras = ["dev", "test"] }284production = { extras = [] }285```286287## Development Workflows288289### Local Development Setup290```bash291# Initialize new project292uv init my-project293cd my-project294295# Set up development environment296uv add --dev black ruff mypy pytest297uv add --dev 'pre-commit>=3.0.0'298299# Create pre-commit config300cat > .pre-commit-config.yaml << EOF301repos:302- repo: https://github.com/astral-sh/ruff-pre-commit303 rev: v0.3.0304 hooks:305 - id: ruff306 args: [--fix]307- repo: https://github.com/psf/black308 rev: 24.2.0309 hooks:310 - id: black311EOF312313# Install pre-commit hooks314uv run pre-commit install315```316317### CI/CD Integration318```yaml319# .github/workflows/python-ci.yml320name: Python CI321322on: [push, pull_request]323324jobs:325 test:326 runs-on: ubuntu-latest327 steps:328 - uses: actions/checkout@v4329330 - name: Install UV331 run: curl -LsSf https://astral.sh/uv/install.sh | sh332333 - name: Setup Python334 run: uv python install 3.12335336 - name: Install dependencies337 run: |338 uv pip install -e ".[test]"339340 - name: Run tests341 run: uv run pytest342```343344### Working with Multiple Python Versions345```bash346# Create test environments347for version in 3.8 3.9 3.10 3.11 3.12; do348 uv venv "venv-$version" --python "$version"349 source "venv-$version/bin/activate"350 uv pip install -e ".[test]"351 uv run pytest352 deactivate353done354```355356## Best Practices357358### 1. Project Structure359```360my-project/361├── .git/362├── .gitignore363├── .pre-commit-config.yaml364├── .python-version365├── .venv/366├── src/367│ └── my_project/368│ ├── __init__.py369│ ├── core.py370│ └── utils/371├── tests/372│ ├── __init__.py373│ └── test_core.py374├── docs/375├── pyproject.toml376├── uv.lock377└── README.md378```379380### 2. Version Control Best Practices381```gitignore382# .gitignore383.venv/384__pycache__/385*.py[cod]386*$py.class387.pytest_cache/388.coverage389htmlcov/390dist/391build/392*.egg-info/393```394395### 3. Dependency Management396- Use semantic versioning for dependencies:397```toml398 dependencies = [399 "requests~=2.28.0", # Compatible releases (>=2.28.0, <2.29.0)400 "flask>=2.0.0,<3.0.0", # Specific version range401 "sqlalchemy==2.0.0", # Exact version402 ]403```404405- Lock dependencies for reproducibility:406```bash407 # Update lockfile408 uv lock409410 # Sync environment with lockfile411 uv sync412```413414### 4. Testing and Quality Assurance415```bash416# Install test dependencies417uv add --dev pytest pytest-cov black mypy ruff418419# Run tests with coverage420uv run pytest --cov=src/my_project421422# Run type checking423uv run mypy src/my_project424425# Run linting426uv run ruff check src/my_project427```428429### 5. Documentation430- Use docstrings for all public APIs431- Maintain up-to-date README.md432- Document environment setup requirements433- Include example usage434435### 6. Security Best Practices436- Keep UV and Python updated437- Use UV's hash verification438- Audit dependencies regularly439- Use private package indexes securely440441### 7. Performance Optimization442- Use UV's concurrent downloads443- Leverage caching effectively444- Optimize dependency resolution445- Use prebuilt wheels when possible446447## Security Considerations448449### Package Verification450```bash451# Enable hash verification452uv pip install --require-hashes -r requirements.txt453454# Generate requirements with hashes455uv pip freeze --all --require-hashes > requirements.txt456```457458### Private Package Indexes459```toml460[tool.uv]461[[tool.uv.index]]462url = "https://private.pypi.org/simple"463username = "${PYPI_USERNAME}"464password = "${PYPI_PASSWORD}"465```466467### Dependency Auditing468```bash469# Install safety checker470uv tool install safety471472# Check for known vulnerabilities473safety check474```475476## Performance Optimization477478### Caching Configuration479```bash480# Set custom cache directory481export UV_CACHE_DIR="/path/to/cache"482483# Clear cache484uv cache clean485486# Prune old cache entries487uv cache prune488```489490### Build Optimization491```bash492# Set concurrent build limit493export UV_CONCURRENT_BUILDS=4494495# Disable build isolation for speed496uv pip install --no-build-isolation package-name497```498499## Troubleshooting500501### Common Issues and Solutions5025031. **Package Installation Failures**504```bash505 # Try with --verbose for more information506 uv pip install --verbose package-name507508 # Force reinstall509 uv pip install --force-reinstall package-name510```5115122. **Virtual Environment Issues**513```bash514 # Recreate virtual environment515 rm -rf .venv516 uv venv517 uv sync518```5195203. **Dependency Conflicts**521```bash522 # Check for conflicts523 uv pip check524525 # Show dependency tree526 uv pip tree527```528529### Debug Mode530```bash531# Enable debug logging532export RUST_LOG=debug533uv pip install package-name534```535536## Environment Variables537538### Common Environment Variables539```bash540# Cache configuration541export UV_CACHE_DIR="/path/to/cache"542export UV_NO_CACHE=1543544# Python configuration545export UV_PYTHON_INSTALL_DIR="/path/to/pythons"546export UV_PYTHON_PREFERENCE="managed"547548# Network configuration549export UV_HTTP_TIMEOUT=30550export UV_OFFLINE=1551552# Build configuration553export UV_CONCURRENT_BUILDS=4554export UV_NO_BUILD_ISOLATION=1555```556557## Tool Integration558559### Editor Integration (VSCode)560```json561{562 "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",563 "python.analysis.typeCheckingMode": "basic",564 "python.formatting.provider": "black",565 "python.linting.enabled": true,566 "python.linting.lintOnSave": true567}568```569570### Pre-commit Integration571```yaml572# .pre-commit-config.yaml573repos:574- repo: https://github.com/astral-sh/ruff-pre-commit575 rev: v0.3.0576 hooks:577 - id: ruff578 args: [--fix]579- repo: https://github.com/psf/black580 rev: 24.2.0581 hooks:582 - id: black583- repo: https://github.com/pre-commit/mirrors-mypy584 rev: v1.8.0585 hooks:586 - id: mypy587 additional_dependencies: [types-all]588```589590### Docker Integration591```dockerfile592FROM python:3.12-slim593594# Install UV595RUN curl -LsSf https://astral.sh/uv/install.sh | sh596597WORKDIR /app598COPY . .599600# Install dependencies601RUN uv pip install -e ".[prod]"602603CMD ["uv", "run", "python", "-m", "my_project"]604```605606## Advanced Package Management607608### Monorepo Support609```610monorepo/611├── .git/612├── pyproject.toml # Workspace configuration613├── project1/614│ ├── pyproject.toml # Project 1 configuration615│ ├── src/616│ └── tests/617├── project2/618│ ├── pyproject.toml # Project 2 configuration619│ ├── src/620│ └── tests/621└── shared/622 ├── pyproject.toml # Shared library configuration623 └── src/624```625626Root pyproject.toml for monorepo:627```toml628[workspace]629members = [630 "project1",631 "project2",632 "shared"633]634635[tool.uv.workspace]636python-version = "3.12"637```638639### Complex Dependency Scenarios6406411. **Git Dependencies with Specific References**642```toml643 dependencies = [644 "mypackage @ git+https://github.com/user/repo.git@main",645 "otherpackage @ git+https://github.com/user/repo.git@v1.0.0",646 "debugtools @ git+ssh://git@github.com/user/repo.git@d34db33f"647 ]648```6496502. **Local Development Dependencies**651```toml652 dependencies = [653 "mypackage @ file:///path/to/package",654 "devtool @ file:///${PROJECT_ROOT}/tools/devtool"655 ]656```6576583. **Complex Version Constraints**659```toml660 dependencies = [661 "requests>=2.28.0,<3.0.0,!=2.29.0", # Exclude specific version662 "flask~=2.0.0", # Compatible release663 "sqlalchemy>2.0.0", # Greater than664 "pandas==2.0.*", # Wildcard matching665 ]666```667668### Advanced Installation Scenarios6696701. **Installing with Extras**671```bash672 # Install multiple extras673 uv add 'flask[async,dotenv]'674675 # Install all extras676 uv add 'flask[all]'677```6786792. **Platform-Specific Dependencies**680```toml681 [project.dependencies]682 pywin32 = { version = ">=305", markers = "sys_platform == 'win32'" }683 pyobjc-framework-Cocoa = { version = ">=9.0", markers = "sys_platform == 'darwin'" }684```6856863. **Development Dependencies with Groups**687```toml688 [project.optional-dependencies]689 test = [690 "pytest>=7.0",691 "pytest-cov>=4.0",692 "pytest-asyncio>=0.21.0"693 ]694 lint = [695 "black>=23.0",696 "ruff>=0.1.0",697 "mypy>=1.0"698 ]699 docs = [700 "sphinx>=7.0",701 "sphinx-rtd-theme>=1.0"702 ]703 dev = [704 "ipython>=8.0",705 "debugpy>=1.6"706 ]707```708709### Package Publishing Workflow710```bash711# Build distribution712uv build713714# Check distribution715uv run twine check dist/*716717# Upload to TestPyPI718uv publish --index testpypi719720# Upload to PyPI721uv publish722723# Upload with trusted publishing (GitHub Actions)724uv publish --oidc725```726727### Advanced Cache Management728```bash729# View cache information730uv cache info731732# Clean specific cache types733uv cache clean --wheels # Clean wheel cache734uv cache clean --sources # Clean source cache735uv cache clean --http # Clean HTTP cache736737# Set cache retention period738uv cache prune --older-than 30d739```740741### Custom Index Configuration742```toml743[tool.uv]744# Configure multiple package indexes745[[tool.uv.index]]746url = "https://pypi.org/simple"747default = true748749[[tool.uv.index]]750url = "https://test.pypi.org/simple"751secondary = true752753[[tool.uv.index]]754url = "https://private.pypi.org/simple"755username = "${PYPI_USERNAME}"756password = "${PYPI_PASSWORD}"757758# Index-specific settings759[tool.uv.index-settings]760timeout = 30761verify-ssl = true762retries = 3763```764765## Common Commands Reference766767### Project Commands768```bash769uv init # Create new project770uv add # Add dependency771uv remove # Remove dependency772uv sync # Install dependencies773uv lock # Update lockfile774uv run # Run command in project environment775```776777### Virtual Environment Commands778```bash779uv venv # Create virtual environment780uv pip install # Install packages781uv pip uninstall # Remove packages782uv pip list # List installed packages783uv pip freeze # Generate requirements.txt784```785786### Python Management Commands787```bash788uv python install # Install Python789uv python list # List Python versions790uv python find # Find Python executable791uv python pin # Pin Python version792```793794### Tool Commands795```bash796uvx # Run tool without installing797uv tool install # Install tool globally798uv tool uninstall # Remove tool799uv tool list # List installed tools800801```
One repository carrying more than one format is the comparison this product exists for: does anyone actually write different content in each file, or is one a copy of the other?
| Repository | Format | Stack | Covers | Score | Changed |
|---|---|---|---|---|---|
| cline/prompts.clinerules/ai-dlc-adaptive-workflow.md · 1.2k | Cline rules | agent-behaviour | 54/100 | today | |
| cline/prompts.clinerules/audio-plugin-developer.md · 1.2k | Cline rules | styleperformancedo-notagent-behaviour | 57/100 | today | |
| cline/prompts.clinerules/ba.md · 1.2k | Cline rules | archgitagent-behaviour | 50/100 | today | |
| cline/prompts.clinerules/baby-steps.md · 1.2k | Cline rules | do-notagent-behaviour | 50/100 | today | |
| cline/prompts.clinerules/c#-guide.md · 1.2k | Cline rules | style | 27/100 | today | |
| cline/prompts.clinerules/claude-code-subagents.md · 1.2k | Cline rules | testarchdo-notagent-behaviour | 77/100 | today | |
| cline/prompts.clinerules/cline-architecture.md · 1.2k | Cline rules | archtypesapi | 54/100 | today | |
| cline/prompts.clinerules/cline-continuous-improvement-protocol.md · 1.2k | Cline rules | testgitperformance | 58/100 | today | |
| cline/prompts.clinerules/cline-for-research.md · 1.2k | Cline rules | agent-behaviour | 34/100 | today | |
| cline/prompts.clinerules/cline-for-slides.md · 1.2k | Cline rules | setupbuildstylearch+1 | 86/100 | today | |
| cline/prompts.clinerules/cline-for-webdev-ui.md · 1.2k | Cline rules | archagent-behaviour | 58/100 | today | |
| cline/prompts.clinerules/code-review.md · 1.2k | Cline rules | lint-formatgitsecurityperformance | 48/100 | today | |
| cline/prompts.clinerules/codebase-onboarding.md · 1.2k | Cline rules | lint-formatstylearchdependencies | 56/100 | today | |
| cline/prompts.clinerules/comprehensive-slide-dev-guide.md · 1.2k | Cline rules | buildarchtypesui | 62/100 | today | |
| cline/prompts.clinerules/create-documentation.md · 1.2k | Cline rules | apidocs | 44/100 | today | |
| cline/prompts.clinerules/gemini-comprehensive-software-engineering-guide.md · 1.2k | Cline rules | buildstyletesting-strategysecurity+4 | 36/100 | today | |
| cline/prompts.clinerules/general-development-rules.md · 1.2k | Cline rules | stylegitdeploymentdo-not | 73/100 | today | |
| cline/prompts.clinerules/google-apps-script-developer.md · 1.2k | Cline rules | setupstylegitsecurity+3 | 66/100 | today | |
| cline/prompts.clinerules/helm-chart-developer.md · 1.2k | Cline rules | setuplint-formatstylearch+6 | 81/100 | today | |
| cline/prompts.clinerules/mcp-development-protocol.md · 1.2k | Cline rules | setupteststyle | 73/100 | today |
Same format, overlapping stack, ranked by quality.
| Repository | Format | Stack | Covers | Score | Changed |
|---|---|---|---|---|---|
| bashdeban/fastmind.clinerules/.project-consistency-keeper2.md · 5 | Cline rules | setupbuildtestlint-format+11 | 100/100 | 14 days ago | |
| blendsdk/appscaffold.clinerules/project.md · 1 | Cline rules | buildteststylearch+3 | 84/100 | 14 days ago | |
| jetstyle/jetstyle-core.clinerules/project-rules.md · 11 | Cline rules | buildstylearchtypes+5 | 81/100 | 14 days ago | |
| sebellows/color-agent.clinerules/python.md · 0 | Cline rules | setuptestlint-formatstyle+3 | 81/100 | 14 days ago | |
| sosan/proxy-llms.clinerules/security.md · 0 | Cline rules | setupstylearchsecurity+1 | 80/100 | 13 days ago | |
| sosan/proxy-llms.clinerules/development-workflow.md · 0 | Cline rules | setuptestarchagent-behaviour | 78/100 | 13 days ago | |
| BattlefieldNoob/Project-Shisha.clinerules/agent-guidelines.md · 0 | Cline rules | setupbuildstyleagent-behaviour+1 | 73/100 | 13 days ago | |
| BattlefieldNoob/Project-Shisha.clinerules/project-context.md · 0 | Cline rules | teststylearchagent-behaviour | 71/100 | 13 days ago |
A badge carrying the measured quality of the strongest agent config file in this repository, out of 100. It reads from this index every time somebody loads your page, so it changes when the measurement changes and there is nothing to keep up to date. Free, no account, and the value is not something you or we can set by hand.
[](https://rulestack.kynth.studio/configs/cline-prompts-clinerules-uv-python-usage-guide)Would rather not hotlink us? Every badge is also served in shields.io’s endpoint schema, so shields renders the image and your readers never talk to our domain:
Published by Toolproof, the masthead over this index and eight others. The method behind the number is at toolproof.kynth.studio/methodology, and the whole thing is readable as JSON with no key at /api.