mirror of
https://github.com/astral-sh/uv.git
synced 2025-08-04 10:58:28 +00:00
127 lines
3.7 KiB
Markdown
127 lines
3.7 KiB
Markdown
# Storage
|
|
|
|
uv persists data in several locations on your system.
|
|
|
|
## Directory Strategies
|
|
|
|
uv follows platform conventions for determining where to store different types of data.
|
|
|
|
Generally, it's best to configure these rather than each uv-specific storage location.
|
|
|
|
### Cache
|
|
|
|
For temporary files and caches:
|
|
|
|
- `$XDG_CACHE_HOME/uv` or `$HOME/.cache/uv` on Unix systems
|
|
- `%LOCALAPPDATA%\uv\cache` on Windows
|
|
|
|
### Data
|
|
|
|
For persistent application data:
|
|
|
|
- `$XDG_DATA_HOME/uv` or `~/.local/share/uv` on Unix systems
|
|
- `%APPDATA%\uv\data` on Windows
|
|
- `.uv` in the working directory as a fallback
|
|
|
|
### Config
|
|
|
|
For user configuration files:
|
|
|
|
- `$XDG_CONFIG_HOME/uv` or `~/.config/uv` on Unix systems
|
|
- `%APPDATA%\uv` on Windows
|
|
|
|
For system configuration files:
|
|
|
|
- `$XDG_CONFIG_DIRS/uv` or `/etc/uv` on Unix systems
|
|
- `%PROGRAMDATA%\uv` on Windows
|
|
|
|
### Binaries
|
|
|
|
For executable files:
|
|
|
|
- `$XDG_BIN_HOME`, `$XDG_DATA_HOME/../bin`, or `~/.local/bin` on all platforms
|
|
|
|
## Cache
|
|
|
|
uv uses a local cache to avoid re-downloading and re-building dependencies. The cache contains
|
|
wheels, source distributions, responses from package indexes, Git repositories, and Python
|
|
interpreter metadata.
|
|
|
|
By default, the cache is stored in the [cache home](#cache).
|
|
|
|
Use `uv cache dir` to show the current cache directory path.
|
|
|
|
Use the `--cache-dir` option or set the `UV_CACHE_DIR` environment variable to configure the cache
|
|
location.
|
|
|
|
For more details, see the [cache documentation](../concepts/cache.md).
|
|
|
|
## Python versions
|
|
|
|
uv can download and manage Python versions.
|
|
|
|
By default, Python versions are stored in the [data home](#data) in a `python/` subdirectory, e.g.,
|
|
`~/.local/share/uv/python`.
|
|
|
|
Use `uv python dir` to show the Python installation directory.
|
|
|
|
Use the `UV_PYTHON_INSTALL_DIR` environment variable to configure the installation directory.
|
|
|
|
For more details, see the [Python versions documentation](../concepts/python-versions.md).
|
|
|
|
### Python executables
|
|
|
|
!!! note
|
|
|
|
This feature is in preview, and is not enabled without `--preview` or `UV_PREVIEW`.
|
|
|
|
uv also supports adding Python executables to your `PATH`.
|
|
|
|
By default, Python executables are stored in the [bin home](#bin).
|
|
|
|
Use `uv python dir --bin` to show the Python executable directory.
|
|
|
|
Use the `UV_PYTHON_BIN_DIR` environment variable to configure the executable directory.
|
|
|
|
## Tools
|
|
|
|
uv can install Python applications as tools using `uv tool install`. Each tool gets its own isolated
|
|
environment.
|
|
|
|
By default, tools are installed in the [data home](#data) under a `tools/` subdirectory, e.g.,
|
|
`~/.local/share/uv/tools`
|
|
|
|
Use `uv tool dir` to show the tool installation directory.
|
|
|
|
Use the `UV_TOOL_DIR` environment variable to configure the installation directory.
|
|
|
|
For more details, see the [tools documentation](../concepts/tools.md).
|
|
|
|
### Tool executables
|
|
|
|
When installing tools, uv will add tools to your `PATH`.
|
|
|
|
By default, tool executbales are stored in the [bin home](#bin).
|
|
|
|
Use `uv tool dir --bin` to show the tool executable directory.
|
|
|
|
Use the `UV_TOOL_BIN_DIR` environment variable to configure the executable directory.
|
|
|
|
## Configuration
|
|
|
|
uv's behavior can be configured through configuration files stored in standard locations.
|
|
|
|
Configuration files are located in the [config directories](#config).
|
|
|
|
For more details, see the [configuration files documentation](../concepts/configuration-files.md).
|
|
|
|
## Project environments
|
|
|
|
uv creates virtual environments for projects to isolate their dependencies.
|
|
|
|
By default, project virtual environments are created in `.venv` within the project directory.
|
|
|
|
Use the `UV_PROJECT_ENVIRONMENT` environment variable to override this location.
|
|
|
|
For more details, see the
|
|
[projects environment documentation](../concepts/projects/config.md#project-environment-path).
|