0
# Tool Management
1
2
UV provides isolated tool execution and installation capabilities, allowing you to run and install Python-packaged tools without affecting your project environment or system Python. Tools are installed in isolated environments with automatic dependency resolution and global availability.
3
4
## Capabilities
5
6
### Tool Execution
7
8
Run Python tools in isolated environments without permanent installation, automatically handling dependencies and environment setup.
9
10
```bash { .api }
11
uv tool run TOOL [ARGS...]
12
# Runs tool in isolated environment
13
# Downloads and installs tool temporarily if not installed
14
15
# Tool specification formats:
16
# tool # Latest version from PyPI
17
# tool@version # Specific version
18
# tool==1.0.0 # Exact version constraint
19
# git+https://... # Git repository
20
# path/to/local # Local path
21
# tool --from package # Tool from different package
22
23
# Options:
24
# --from PACKAGE # Install tool from specific package
25
# --with DEPENDENCY # Add temporary dependencies
26
# --python VERSION # Python version to use
27
# --isolated # Force isolated environment
28
# --no-project # Ignore project configuration
29
```
30
31
Usage examples:
32
33
```bash
34
# Run black formatter
35
uv tool run black .
36
37
# Run specific version
38
uv tool run black@23.0.0 .
39
40
# Run with additional dependencies
41
uv tool run --with requests httpie http://example.com
42
43
# Run tool from different package
44
uv tool run --from django-admin django-admin startproject myproject
45
46
# Run from Git repository
47
uv tool run git+https://github.com/psf/black.git .
48
```
49
50
### Tool Installation
51
52
Install Python tools globally for persistent availability across projects and shell sessions.
53
54
```bash { .api }
55
uv tool install TOOL
56
# Installs tool globally in isolated environment
57
# Makes tool commands available in PATH
58
59
# Tool specification formats:
60
# tool # Latest version from PyPI
61
# tool@version # Specific version
62
# tool==1.0.0 # Exact version constraint
63
# git+https://... # Git repository
64
# path/to/local # Local path
65
66
# Options:
67
# --from PACKAGE # Install from specific package
68
# --with DEPENDENCY # Include additional dependencies
69
# --python VERSION # Python version to use
70
# --force # Force reinstall if exists
71
# --editable # Install as editable (local paths)
72
```
73
74
Usage examples:
75
76
```bash
77
# Install black formatter
78
uv tool install black
79
80
# Install specific version
81
uv tool install black@23.0.0
82
83
# Install with additional dependencies
84
uv tool install --with keyring twine
85
86
# Install from Git
87
uv tool install git+https://github.com/astral-sh/ruff.git
88
89
# Force reinstall
90
uv tool install black --force
91
92
# Install editable local tool
93
uv tool install --editable ./my-tool/
94
```
95
96
### Tool Listing and Information
97
98
List installed tools and show detailed information about tool installations.
99
100
```bash { .api }
101
uv tool list
102
uv tool ls # Alias for list
103
# Lists all installed tools with versions and entry points
104
105
# Options:
106
# --show-paths # Show installation paths
107
# --format FORMAT # Output format (text/json)
108
```
109
110
Usage examples:
111
112
```bash
113
# List all installed tools
114
uv tool list
115
116
# Show tool installation paths
117
uv tool list --show-paths
118
119
# Get machine-readable output
120
uv tool list --format json
121
```
122
123
### Tool Updates and Upgrades
124
125
Update tools to their latest versions with dependency resolution and conflict checking.
126
127
```bash { .api }
128
uv tool upgrade TOOL...
129
# Upgrades installed tools to latest versions
130
131
# Options:
132
# --all # Upgrade all installed tools
133
```
134
135
Usage examples:
136
137
```bash
138
# Upgrade specific tool
139
uv tool upgrade black
140
141
# Upgrade multiple tools
142
uv tool upgrade black ruff mypy
143
144
# Upgrade all installed tools
145
uv tool upgrade --all
146
```
147
148
### Tool Uninstallation
149
150
Remove installed tools and clean up their isolated environments.
151
152
```bash { .api }
153
uv tool uninstall TOOL...
154
# Uninstalls tools and removes their environments
155
156
# Options:
157
# --all # Uninstall all tools
158
```
159
160
Usage examples:
161
162
```bash
163
# Uninstall specific tool
164
uv tool uninstall black
165
166
# Uninstall multiple tools
167
uv tool uninstall black ruff mypy
168
169
# Uninstall all tools
170
uv tool uninstall --all
171
```
172
173
### PATH Management
174
175
Ensure tool binaries are available in the system PATH for seamless command-line access.
176
177
```bash { .api }
178
uv tool update-shell
179
# Updates shell configuration to include tool directory in PATH
180
# Modifies .bashrc, .zshrc, or equivalent shell config
181
182
# Alias:
183
uv tool ensurepath
184
185
# Options:
186
# --shell SHELL # Specify shell type
187
```
188
189
Usage examples:
190
191
```bash
192
# Update shell PATH configuration
193
uv tool update-shell
194
195
# Update for specific shell
196
uv tool update-shell --shell zsh
197
198
# Alternative command name
199
uv tool ensurepath
200
```
201
202
### Tool Directory Management
203
204
Show and manage tool installation directories and configuration.
205
206
```bash { .api }
207
uv tool dir
208
# Shows tool installation directory
209
# Location where uv stores tool environments
210
211
# Options:
212
# --bin # Show binary directory
213
```
214
215
Usage examples:
216
217
```bash
218
# Show tool installation directory
219
uv tool dir
220
221
# Show tool binary directory
222
uv tool dir --bin
223
```
224
225
## Tool Discovery and Entry Points
226
227
UV automatically discovers and manages entry points from installed tools:
228
229
- **Console Scripts**: Primary command-line interfaces defined in package metadata
230
- **GUI Scripts**: Graphical applications (on platforms that support them)
231
- **Module Execution**: Tools that support `python -m module` execution
232
233
When you install a tool, UV:
234
1. Creates an isolated virtual environment for the tool
235
2. Installs the tool and its dependencies
236
3. Links entry points to the global tool binary directory
237
4. Makes commands available in PATH (after shell configuration)
238
239
## Tool Isolation Benefits
240
241
Each tool runs in its own isolated environment, providing:
242
243
- **Dependency Isolation**: No conflicts between tool dependencies
244
- **Version Isolation**: Multiple versions of tools can coexist
245
- **System Protection**: No impact on system or project Python environments
246
- **Clean Uninstalls**: Complete removal of tools and dependencies
247
248
## Tool Specification Formats
249
250
UV supports flexible tool specification:
251
252
```bash { .api }
253
# Package names:
254
black # Latest version
255
ruff # Latest version
256
257
# Version constraints:
258
black@23.0.0 # Specific version
259
black>=23.0.0 # Minimum version
260
black==23.0.0,<24.0.0 # Version range
261
262
# Git repositories:
263
git+https://github.com/psf/black.git
264
git+https://github.com/psf/black.git@main
265
git+https://github.com/psf/black.git@v23.0.0
266
267
# Local paths:
268
./my-tool # Relative path
269
/path/to/tool # Absolute path
270
~/dev/my-tool # Home directory path
271
272
# URLs:
273
https://files.pythonhosted.org/packages/.../tool.whl
274
275
# Tool from different package:
276
--from django django-admin # Install django-admin from django package
277
--from jupyter jupyter-lab # Install jupyter-lab from jupyter package
278
```
279
280
## Common Tool Examples
281
282
Popular Python tools that work well with UV tool management:
283
284
```bash { .api }
285
# Code formatting and linting:
286
uv tool install black # Code formatter
287
uv tool install ruff # Fast linter and formatter
288
uv tool install mypy # Type checker
289
uv tool install flake8 # Style guide enforcement
290
uv tool install isort # Import sorter
291
292
# Development tools:
293
uv tool install poetry # Dependency management
294
uv tool install pipx # Tool installer (alternative to uv tool)
295
uv tool install pre-commit # Git hooks framework
296
uv tool install tox # Testing in multiple environments
297
298
# Publishing and packaging:
299
uv tool install twine # PyPI package uploader
300
uv tool install build # PEP 517/518 build frontend
301
uv tool install wheel # Wheel package format
302
303
# Web development:
304
uv tool install django-admin # Django admin command
305
uv tool install flask # Flask web framework CLI
306
uv tool install cookiecutter # Project templates
307
308
# Data science:
309
uv tool install jupyter # Jupyter notebooks
310
uv tool install jupyterlab # JupyterLab IDE
311
uv tool install datasette # Data exploration tool
312
313
# Documentation:
314
uv tool install mkdocs # Documentation generator
315
uv tool install sphinx # Documentation tool
316
uv tool install pdoc # API documentation
317
```
318
319
## Tool Environment Configuration
320
321
Configure tool behavior through UV settings:
322
323
```toml { .api }
324
[tool.uv]
325
# Tool installation settings
326
tool-python = "3.12" # Default Python for tools
327
tool-upgrade = true # Auto-upgrade tools
328
329
[tool.uv.tool-sources]
330
# Custom tool sources
331
black = { git = "https://github.com/psf/black.git" }
332
ruff = { path = "./local-ruff" }
333
```
334
335
## Integration with uvx
336
337
The `uvx` binary provides a shortcut for `uv tool run`:
338
339
```bash { .api }
340
# These are equivalent:
341
uvx black .
342
uv tool run black .
343
344
# Version specification:
345
uvx black@23.0.0 .
346
uv tool run black@23.0.0 .
347
348
# With additional dependencies:
349
uvx --with requests httpie http://example.com
350
uv tool run --with requests httpie http://example.com
351
```
352
353
## Tool Environment Variables
354
355
Control tool behavior with environment variables:
356
357
```bash { .api }
358
UV_TOOL_DIR=/custom/tools # Custom tool directory
359
UV_TOOL_BIN_DIR=/custom/bin # Custom binary directory
360
UV_NO_PROGRESS=1 # Disable progress bars
361
```
362
363
## Troubleshooting Tool Installation
364
365
Common issues and solutions:
366
367
1. **Command not found**: Run `uv tool update-shell` to update PATH
368
2. **Tool conflicts**: Each tool is isolated, so conflicts shouldn't occur
369
3. **Version issues**: Use specific version constraints or `--force` to reinstall
370
4. **Permission errors**: UV installs to user directory, no sudo required
371
5. **Path issues**: Check `uv tool dir --bin` and ensure it's in PATH