diff --git a/docs/configuration/files.md b/docs/configuration/files.md
index 122f251d5a34..58c6dc99550a 100644
--- a/docs/configuration/files.md
+++ b/docs/configuration/files.md
@@ -33,6 +33,12 @@ uv will also search for `uv.toml` files, which follow an identical structure, bu
 index-url = "https://test.pypi.org/simple"
 ```
 
+!!! note
+
+    `uv.toml` files take precedence over `pyproject.toml` files, so if both `uv.toml` and
+    `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. User-level
 configuration must use the `uv.toml` format, rather than the `pyproject.toml` format, as a