🐍 vx-tool-uv

🎯 Overview

vx-tool-uv provides UV (Extremely fast Python package installer and resolver) support for vx, enabling automatic installation, version management, and execution of UV commands through the vx interface. Enhanced with the vx-installer engine for beautiful installation experiences.

✨ Features

🚀 Enhanced Installation Experience

• 📊 Beautiful Progress Bars: Rich progress tracking during UV installation and package operations
• 🔒 Security First: Automatic checksum verification and secure downloads
• ⚡ Lightning Performance: 10-100x faster than traditional pip with concurrent operations

🐍 Core UV Features

• UV Package Manager: Extremely fast Python package installation and dependency resolution
• UVX Support: Python application runner with complete environment isolation
• Auto-Installation: Zero-configuration automatic download and installation of UV
• Cross-Platform: Seamless operation on Windows, macOS, and Linux
• Virtual Environment: Advanced integration with UV's venv management
• Pip Compatibility: Drop-in replacement for pip commands with enhanced performance
• 🤖 MCP Ready: Perfect for MCP servers requiring Python tools

Supported Commands

UV Package Manager

# Package installation
vx uv pip install requests
vx uv pip install -r requirements.txt
vx uv pip install -e .

# Package management
vx uv pip uninstall requests
vx uv pip list
vx uv pip show requests
vx uv pip freeze

# Virtual environments
vx uv venv myenv
vx uv venv --python 3.11
vx uv pip install --system requests

UVX Application Runner

# 🎯 Perfect for MCP servers - just add 'vx'!
vx uvx ruff check .                  # Auto-installs ruff via UV
vx uvx black .                       # Auto-installs black via UV
vx uvx pytest                        # Auto-installs pytest via UV
vx uvx cowsay -t "Hello from vx!"    # One-time tool execution

# 🤖 MCP Integration Example
# Instead of: uvx some-python-tool
# Use:        vx uvx some-python-tool
# Benefits: Auto-installation, environment isolation, progress tracking

# Run with specific versions
vx uvx --python 3.11 black .
vx uvx --from black==23.0.0 black .

# Install and run
vx uvx --install-only ruff
vx uvx ruff check .

UV Project Management

# Initialize projects
vx uv init myproject
vx uv init --lib mylib

# Add dependencies
vx uv add requests
vx uv add --dev pytest
vx uv add "django>=4.0"

# Run commands
vx uv run python script.py
vx uv run pytest
vx uv run --python 3.11 python script.py

Installation

Through vx CLI

# Install latest version
vx install uv

# Install specific version
vx install uv@0.1.5
vx install uv@latest

Version Constraints

# Semantic version ranges
vx install uv@^0.1.0      # Latest 0.1.x
vx install uv@~0.1.5      # Latest 0.1.5.x
vx install uv@>=0.1.0     # 0.1.0 or higher

Configuration

Project Configuration (.vx.toml)

[tools]
uv = "latest"             # Latest stable version
# uv = "0.1.5"            # Specific version
# uv = "^0.1.0"           # Version range

[tools.uv]
auto_install = true
python_version = "3.11"   # Default Python version

Global Configuration

[tools.uv]
default_version = "latest"
auto_install = true
install_timeout = 300

[uv.settings]
index_url = "https://pypi.org/simple/"
extra_index_url = []
trusted_host = []
cache_dir = "~/.cache/uv"

Python Version Management

Python Discovery

UV automatically discovers Python installations:

# Use system Python
vx uv --python python3.11 pip install requests

# Use specific Python path
vx uv --python /usr/bin/python3.11 pip install requests

# Use Python from PATH
vx uv --python 3.11 pip install requests

Virtual Environment Integration

# Create virtual environment
vx uv venv .venv

# Activate and use
source .venv/bin/activate  # Unix
.venv\Scripts\activate     # Windows

# Or use uv run directly
vx uv run python script.py

Platform Support

Windows

• x64: Full support
• x86: Limited support
• ARM64: Windows 11 ARM support

macOS

• x64: Intel Mac support
• ARM64: Apple Silicon (M1/M2) support
• Universal: Automatic architecture detection

Linux

• x64: All major distributions
• ARM64: ARM-based systems
• musl: Alpine Linux support

Performance Benefits

Speed Comparison

• 10-100x faster than pip for package installation
• Parallel downloads and installations
• Efficient dependency resolution
• Smart caching of packages and metadata

Benchmarks

# Traditional pip
time pip install django flask fastapi  # ~30 seconds

# UV
time vx uv pip install django flask fastapi  # ~3 seconds

Integration

With vx-core

use vx_core::{Tool, ToolManager};
use vx_tool_uv::UvTool;

let uv_tool = UvTool::new();
let manager = ToolManager::new();

// Install UV
manager.install_tool(&uv_tool, "latest").await?;

// Execute UV commands
manager.execute_tool(&uv_tool, &["pip", "install", "requests"]).await?;

Plugin Registration

use vx_core::{Plugin, PluginManager};
use vx_tool_uv::UvPlugin;

let plugin = UvPlugin::new();
let mut manager = PluginManager::new();

manager.register_plugin(Box::new(plugin))?;

Development

Building

cd crates/vx-tool-uv
cargo build

Testing

cargo test

Integration Testing

# Test with actual UV installation
cargo test --features integration-tests

Implementation Details

Tool Structure

• UvTool: Main UV package manager tool
• UvxTool: UVX application runner support
• UvProjectTool: UV project management commands

Version Resolution

1. Project Config: Check .vx.toml for version specification
2. Global Config: Fall back to global default
3. Latest Stable: Use latest stable if no version specified
4. Auto-Install: Download and install if not available

Installation Process

1. Version Lookup: Query UV release API
2. Download: Fetch appropriate binary for platform
3. Extraction: Extract to vx tools directory
4. Verification: Verify installation integrity
5. Configuration: Set up UV configuration

Migration from Pip

Command Mapping

# pip commands -> uv equivalents
pip install requests        → vx uv pip install requests
pip install -r requirements.txt → vx uv pip install -r requirements.txt
pip uninstall requests      → vx uv pip uninstall requests
pip list                    → vx uv pip list
pip freeze                  → vx uv pip freeze
pip show requests           → vx uv pip show requests

Configuration Migration

# pip.conf -> uv configuration
[global]
index-url = https://pypi.org/simple/
extra-index-url = https://test.pypi.org/simple/

# Equivalent UV configuration
[uv.settings]
index_url = "https://pypi.org/simple/"
extra_index_url = ["https://test.pypi.org/simple/"]

Error Handling

Common Errors

• Network Issues: Download failures, index timeouts
• Permission Errors: Installation directory access
• Python Not Found: Missing Python installation
• Package Conflicts: Dependency resolution failures

Recovery

# Reinstall UV
vx install uv --force

# Clear UV cache
vx uv cache clean

# Use system pip as fallback
vx --use-system-path pip install requests

Security

• Checksum Verification: SHA256 verification of downloads
• HTTPS Only: Secure downloads from official sources
• Package Verification: Verification of package integrity
• Isolated Execution: Sandboxed package installation

Troubleshooting

Installation Issues

# Check UV installation
vx uv --version

# Verify Python availability
vx uv --python python3 --version

# Check UV cache
vx uv cache info

# Force reinstall
vx remove uv
vx install uv

Runtime Issues

# Debug UV commands
vx uv --verbose pip install requests

# Check UV configuration
vx uv pip config list

# Test with system Python
vx uv --python /usr/bin/python3 pip install requests

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Contributions are welcome! Please see the contributing guidelines for more information.

Related Crates

• vx-core - Core functionality
• vx-cli - Command-line interface
• vx-tool-node - Node.js tool
• vx-tool-python - Python tool