vx-tool-uv 0.2.2

UV tool support for vx
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351

# vx-tool-uv


[![Crates.io](https://img.shields.io/crates/v/vx-tool-uv.svg)](https://crates.io/crates/vx-tool-uv)
[![Documentation](https://docs.rs/vx-tool-uv/badge.svg)](https://docs.rs/vx-tool-uv)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# Install latest version

vx install uv

# Install specific version

vx install uv@0.1.5
vx install uv@latest
```

### Version Constraints

```bash
# 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)

```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

```toml
[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:

```bash
# 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

```bash
# 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

```bash
# 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

```rust
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

```rust
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

```bash
cd crates/vx-tool-uv
cargo build
```

### Testing

```bash
cargo test
```

### Integration Testing

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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](../../../LICENSE) file for details.

## Contributing


Contributions are welcome! Please see the [contributing guidelines](../../../CONTRIBUTING.md) for more information.

## Related Crates


- [`vx-core`](../../vx-core/README.md) - Core functionality
- [`vx-cli`](../../vx-cli/README.md) - Command-line interface
- [`vx-tool-node`](../vx-tool-node/README.md) - Node.js tool
- [`vx-tool-python`](../vx-tool-python/README.md) - Python tool