vx-tool-uv 0.2.5

UV tool support for vx
Documentation

vx-tool-uv

Crates.io Documentation License: MIT

UV Python tool support for the vx universal tool manager.

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.

Features

  • UV Package Manager: Lightning-fast Python package installation
  • UVX Support: Python application runner with environment isolation
  • Auto-Installation: Automatic download and installation of UV
  • Cross-Platform: Windows, macOS, and Linux support
  • Virtual Environment: Seamless integration with UV's venv management
  • Pip Compatibility: Drop-in replacement for pip commands
  • Performance: 10-100x faster than traditional pip

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

# Run Python applications
vx uvx ruff check .
vx uvx black .
vx uvx pytest

# 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