diff --git a/docs/concepts/configuration-files.md b/docs/concepts/configuration-files.md index 05dcbdb35f094..e034bd198fbc3 100644 --- a/docs/concepts/configuration-files.md +++ b/docs/concepts/configuration-files.md @@ -42,13 +42,14 @@ default = true `pyproject.toml` files are present in a directory, configuration will be read from `uv.toml`, and `[tool.uv]` section in the accompanying `pyproject.toml` will be ignored. -uv will also discover user-level configuration at `~/.config/uv/uv.toml` (or -`$XDG_CONFIG_HOME/uv/uv.toml`) on macOS and Linux, or `%APPDATA%\uv\uv.toml` on Windows; and -system-level configuration at `/etc/uv/uv.toml` (or `$XDG_CONFIG_DIRS/uv/uv.toml`) on macOS and -Linux, or `%SYSTEMDRIVE%\ProgramData\uv\uv.toml` on Windows. +uv will also discover `uv.toml` configuration files in the user- and system-level +[configuration directories](../reference/storage.md#configuration-directories), e.g., user-level +configuration in `~/.config/uv/uv.toml`, and system-level configuration at `/etc/uv/uv.toml` on +macOS and Linux. -User-and system-level configuration must use the `uv.toml` format, rather than the `pyproject.toml` -format, as a `pyproject.toml` is intended to define a Python _project_. +!!! important + + User- and system-level configuration files cannot use the `pyproject.toml` format. If project-, user-, and system-level configuration files are found, the settings will be merged, with project-level configuration taking precedence over the user-level configuration, and user-level diff --git a/docs/concepts/python-versions.md b/docs/concepts/python-versions.md index bcb40ccd2fe6f..65576ef7879c2 100644 --- a/docs/concepts/python-versions.md +++ b/docs/concepts/python-versions.md @@ -121,10 +121,15 @@ present, uv will install all the Python versions listed in the file. The available Python versions are frozen for each uv release. To install new Python versions, you may need upgrade uv. +See the [storage documentation](../reference/storage.md#python-versions) for details about where +installed Python versions are stored. + ### Installing Python executables -uv installs Python executables into your `PATH` by default, e.g., `uv python install 3.12` will -install a Python executable into `~/.local/bin`, e.g., as `python3.12`. +uv installs Python executables into your `PATH` by default, e.g., on Unix `uv python install 3.12` +will install a Python executable into `~/.local/bin`, e.g., as `python3.12`. See the +[storage documentation](../reference/storage.md#python-executables) for more details about the +target directory. !!! tip diff --git a/docs/concepts/tools.md b/docs/concepts/tools.md index b721dfa8e0d5a..5362932e93e1e 100644 --- a/docs/concepts/tools.md +++ b/docs/concepts/tools.md @@ -35,9 +35,14 @@ treated as disposable, i.e., if you run `uv cache clean` the environment will be environment is only cached to reduce the overhead of repeated invocations. If the environment is removed, a new one will be created automatically. -When installing a tool with `uv tool install`, a virtual environment is created in the uv tools -directory. The environment will not be removed unless the tool is uninstalled. If the environment is -manually deleted, the tool will fail to run. +When installing a tool with `uv tool install`, a virtual environment is created in the +[uv tools directory](../reference/storage.md#tools). The environment will not be removed unless the +tool is uninstalled. If the environment is manually deleted, the tool will fail to run. + +!!! important + + Tool environments are _not_ intended to be mutated directly. It is strongly recommended never to + mutate a tool environment manually, e.g., with a `pip` operation. ## Tool versions @@ -109,26 +114,6 @@ $ uv tool install ruff@latest $ uv tool install ruff@0.6.0 ``` -## Tools directory - -By default, the uv tools directory is named `tools` and is in the uv application state directory, -e.g., `~/.local/share/uv/tools`. The location may be customized with the `UV_TOOL_DIR` environment -variable. - -To display the path to the tool installation directory: - -```console -$ uv tool dir -``` - -Tool environments are placed in a directory with the same name as the tool package, e.g., -`.../tools/`. - -!!! important - - Tool environments are _not_ intended to be mutated directly. It is strongly recommended never to - mutate a tool environment manually, e.g., with a `pip` operation. - ## Upgrading tools Tool environments may be upgraded via `uv tool upgrade`, or re-created entirely via subsequent @@ -259,35 +244,23 @@ tool may be unusable. ## Tool executables Tool executables include all console entry points, script entry points, and binary scripts provided -by a Python package. Tool executables are symlinked into the `bin` directory on Unix and copied on -Windows. - -### The `bin` directory - -Executables are installed into the user `bin` directory following the XDG standard, e.g., -`~/.local/bin`. Unlike other directory schemes in uv, the XDG standard is used on _all platforms_ -notably including Windows and macOS — there is no clear alternative location to place executables on -these platforms. The installation directory is determined from the first available environment -variable: +by a Python package. Tool executables are symlinked into the +[executable directory](../reference/storage.md#tool-executables) on Unix and copied on Windows. -- `$UV_TOOL_BIN_DIR` -- `$XDG_BIN_HOME` -- `$XDG_DATA_HOME/../bin` -- `$HOME/.local/bin` - -Executables provided by dependencies of tool packages are not installed. +!!! note -### The `PATH` + Executables provided by dependencies of tool packages are not installed. -The `bin` directory must be in the `PATH` variable for tool executables to be available from the -shell. If it is not in the `PATH`, a warning will be displayed. The `uv tool update-shell` command -can be used to add the `bin` directory to the `PATH` in common shell configuration files. +The [executable directory](../reference/storage.md#executable-directory) must be in the `PATH` +variable for tool executables to be available from the shell. If it is not in the `PATH`, a warning +will be displayed. The `uv tool update-shell` command can be used to add the executable directory to +the `PATH` in common shell configuration files. ### Overwriting executables -Installation of tools will not overwrite executables in the `bin` directory that were not previously -installed by uv. For example, if `pipx` has been used to install a tool, `uv tool install` will -fail. The `--force` flag can be used to override this behavior. +Installation of tools will not overwrite executables in the executable directory that were not +previously installed by uv. For example, if `pipx` has been used to install a tool, +`uv tool install` will fail. The `--force` flag can be used to override this behavior. ## Relationship to `uv run` diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md index 0f269591bffa2..635879af5fe93 100644 --- a/docs/getting-started/installation.md +++ b/docs/getting-started/installation.md @@ -260,7 +260,8 @@ If you need to remove uv from your system, follow these steps: !!! tip - Before removing the binaries, you may want to remove any data that uv has stored. + Before removing the binaries, you may want to remove any data that uv has stored. See the + [storage reference](../reference/storage.md) for details on where uv stores data. 2. Remove the uv, uvx, and uvw binaries: diff --git a/docs/reference/index.md b/docs/reference/index.md index 0c9102ef913ad..474b4121f4e56 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -5,6 +5,7 @@ The reference section provides information about specific parts of uv: - [Commands](./cli.md): A reference for uv's command line interface. - [Settings](./settings.md): A reference for uv's configuration schema. - [Resolver](./internals/resolver.md): Details about the internals of uv's resolver. +- [Storage](./storage.md): Information about where uv stores data on your system. - [Policies](./policies/index.md): uv's versioning policy, platform support policy, and license. Looking for a broader overview? Check out the [concepts](../concepts/index.md) documentation. diff --git a/docs/reference/installer.md b/docs/reference/installer.md index 609a8f7ecf7c8..5128bc262c1ef 100644 --- a/docs/reference/installer.md +++ b/docs/reference/installer.md @@ -2,9 +2,7 @@ ## Changing the installation path -By default, uv is installed to `~/.local/bin`. If `XDG_BIN_HOME` is set, it will be used instead. -Similarly, if `XDG_DATA_HOME` is set, the target directory will be inferred as -`XDG_DATA_HOME/../bin`. +By default, uv is installed in the user [executable directory](./storage.md#executable-directory). To change the installation path, use `UV_INSTALL_DIR`: @@ -20,6 +18,12 @@ To change the installation path, use `UV_INSTALL_DIR`: PS> powershell -ExecutionPolicy ByPass -c {$env:UV_INSTALL_DIR = "C:\Custom\Path";irm https://astral.sh/uv/install.ps1 | iex} ``` +!!! note + + Changing the installation path only affects where the uv binary is installed. uv will still store + its data (cache, Python installations, tools, etc.) in the default locations. See the + [storage reference](./storage.md) for details on these locations and how to customize them. + ## Disabling shell modifications The installer may also update your shell profiles to ensure the uv binary is on your `PATH`. To diff --git a/docs/reference/storage.md b/docs/reference/storage.md new file mode 100644 index 0000000000000..44cd201516b84 --- /dev/null +++ b/docs/reference/storage.md @@ -0,0 +1,200 @@ +# Storage + +## Storage directories + +uv uses the following high-level directories for storage. + +For each location, uv checks for the existence of environment variables in the given order and uses +the first path found. + +The paths of storage directories are platform-specific. uv follows the +[XDG](https://specifications.freedesktop.org/basedir-spec/latest/) conventions on Linux and macOS +and the [Known Folder](https://learn.microsoft.com/en-us/windows/win32/shell/known-folders) scheme +on Windows. + +### Temporary directory + +The temporary directory is used for ephemeral data. + +=== "Unix" + + 1. `$TMPDIR` + 1. `/tmp` + +=== "Windows" + + 1. `%TMP%` + 1. `%TEMP%` + 1. `%USERPROFILE%` + +### Cache directory + +The cache directory is used for data that is disposable, but is useful to be long-lived. + +=== "Unix" + + 1. `$XDG_CACHE_HOME/uv` + 1. `$HOME/.cache/uv` + +=== "Windows" + + 1. `%LOCALAPPDATA%\uv\cache` + 1. `uv\cache` within [`FOLDERID_LocalAppData`](https://learn.microsoft.com/en-us/windows/win32/shell/knownfolderid#FOLDERID_LocalAppData) + +### Persistent data directory + +The persistent data directory is used for non-disposable data. + +=== "Unix" + + 1. `$XDG_DATA_HOME/uv` + 1. `$HOME/.local/share/uv` + 1. `$CWD/.uv` + +=== "Windows" + + 1. `%APPDATA%\uv\data` + 1. `.\.uv` + +### Configuration directories + +The configuration directories are used to store changes to uv's settings. + +User-level configuration + +=== "Unix" + + 1. `$XDG_CONFIG_HOME/uv` + 1. `$HOME/.config/uv` + +=== "Windows" + + 1. `%APPDATA%\uv` + 1. `uv` within [`FOLDERID_RoamingAppData`](https://learn.microsoft.com/en-us/windows/win32/shell/knownfolderid#FOLDERID_RoamingAppData) + +System-level configuration + +=== "Unix" + + 1. `$XDG_CONFIG_DIRS/uv` + 1. `/etc/uv` + +=== "Windows" + + 1. `%PROGRAMDATA%\uv` + 1. `uv` within [`FOLDERID_AppDataProgramData`](https://learn.microsoft.com/en-us/windows/win32/shell/knownfolderid#FOLDERID_AppDataProgramData) + +### Executable directory + +The executable directory is used to store files that can be run by the user, i.e., a directory that +should be on the `PATH`. + +=== "Unix" + + 1. `$XDG_BIN_HOME` + 1. `$XDG_DATA_HOME/../bin` + 1. `$HOME/.local/bin` + +=== "Windows" + + 1. `%XDG_BIN_HOME%` + 1. `%XDG_DATA_HOME%\..\bin` + 1. `%USERPROFILE%\.local\bin` + +## Types of data + +### Dependency cache + +uv uses a local cache to avoid re-downloading and re-building dependencies. + +By default, the cache is stored in the [cache directory](#cache-directory) but it can be overridden +via command line arguments, environment variables, or settings as detailed in +[the cache documentation](../concepts/cache.md#cache-directory). When the cache is disabled, the +cache will be stored in a [temporary directory](#temporary-directory). + +Use `uv cache dir` to show the current cache directory path. + +!!! important + + For optimal performance, the cache directory needs to be on the same filesystem as virtual + environments. + +### Python versions + +uv can install managed [Python versions](../concepts/python-versions.md), e.g., with +`uv python install`. + +By default, Python versions managed by uv are stored in a `python/` subdirectory of the +[persistent data directory](#persistent-data-directory), 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 override the installation directory. + +!!! note + + Changing where Python is installed will not be automatically reflected in existing virtual environments; they will keep referring to the old location, and will need to be updated manually (e.g. by re-creating them). + +### Python executables + +uv installs executables for [Python versions](#python-versions), e.g., `python3.13`. + +By default, Python executables are stored in the [executable directory](#executable-directory). + +Use `uv python dir --bin` to show the Python executable directory. + +Use the `UV_PYTHON_BIN_DIR` environment variable to override the Python executable directory. + +### Tools + +uv can install Python packages as [command-line tools](../concepts/tools.md) using +`uv tool install`. + +By default, tools are installed in a `tools/` subdirectory of the +[persistent data directory](#persistent-data-directory), 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. + +### Tool executables + +uv installs executables for installed [tools](#tools), e.g., `ruff`. + +By default, tool executables are stored in the [executable directory](#executable-directory). + +Use `uv tool dir --bin` to show the tool executable directory. + +Use the `UV_TOOL_BIN_DIR` environment variable to configure the tool executable directory. + +### The uv executable + +When using uv's [standalone installer](./installer.md) to install uv, the `uv` and `uvx` executables +are installed into the [executable directory](#executable-directory). + +Use the `UV_INSTALL_DIR` environment variable to configure uv's installation directory. + +### Configuration files + +uv's behavior can be configured through TOML files. + +Configuration files are discovered in the [configuration directories](#configuration-directories). + +For more details, see the [configuration files documentation](../concepts/configuration-files.md). + +### Project virtual environments + +When working on [projects](../concepts/projects/index.md), uv creates a dedicated virtual +environment for each project. + +By default, project virtual environments are created in `.venv` in the project or workspace root, +i.e., next to the `pyproject.toml`. + +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). + +### Script virtual environments + +When running [scripts with inline metadata](../guides/scripts.md), uv creates a dedicated virtual +environment for each script in the [cache directory](#cache-directory). diff --git a/mkdocs.template.yml b/mkdocs.template.yml index 50f9f4e01ff54..e6823f3db9b15 100644 --- a/mkdocs.template.yml +++ b/mkdocs.template.yml @@ -144,6 +144,7 @@ plugins: Reference: - reference/cli.md - reference/settings.md + - reference/storage.md - reference/environment.md - reference/installer.md extra_css: @@ -236,6 +237,7 @@ nav: - Commands: reference/cli.md - Settings: reference/settings.md - Environment variables: reference/environment.md + - Storage: reference/storage.md - Installer options: reference/installer.md - Troubleshooting: - reference/troubleshooting/index.md