From eec99f9349530f29b6a9919d0bb93b43de4c6986 Mon Sep 17 00:00:00 2001 From: Charlie Marsh Date: Wed, 8 May 2024 15:03:17 -0400 Subject: [PATCH] Add basic documentation for persistent configuration (#3467) --- README.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/README.md b/README.md index 32a9c3a71..47d998b66 100644 --- a/README.md +++ b/README.md @@ -199,6 +199,52 @@ of `distutils` (but not `sysconfig`)](https://ffy00.github.io/blog/02-python-deb While we always recommend the use of virtual environments, uv considers them to be required in these non-standard environments. +### Persistent configuration + +uv supports persistent configuration at both the project- and user-level. + +Specifically, uv will search for a `pyproject.toml` or `uv.toml` file in the current directory, or +in the nearest parent directory. + +If a `pyproject.toml` file is found, uv will read configuration from the `[tool.uv.pip]` table. +For example, to set a persistent index URL, add the following to a `pyproject.toml`: + +```toml +[tool.uv.pip] +index-url = "https://test.pypi.org/simple" +``` + +(If there is no such table, the `pyproject.toml` file be ignored, and uv will continue searching in +the directory hierarchy.) + +If a `uv.toml` file is found, uv will read from the `[pip]` table. For example: + +```toml +[pip] +index-url = "https://test.pypi.org/simple" +``` + +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. User-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_. + +If both project- and user-level configuration are found, the settings will be merged, with the +project-level configuration taking precedence. Specifically, if a string, number, or boolean is +present in both tables, the project-level value will be used, and the user-level value will be +ignored. If an array is present in both tables, the arrays will be concatenated, with the +project-level settings appearing later in the merged array. + +Settings provided via environment variables take precedence over persistent configuration, and +settings provided via the command line take precedence over both. + +uv accepts a `--isolated` command-line argument which, when provided, disables the discovery of any +persistent configuration. + +uv also accepts a `--config-file` command-line argument, which accepts a path to a `uv.toml` to use +as the configuration file. When provided, this file will be used in place of _any_ discovered +configuration files (e.g., user-level configuration will be ignored). + ### Git authentication uv allows packages to be installed from Git and supports the following schemes for authenticating with private