Add support for .env and custom env files in uv run (#8811)

## Summary

This PR pulls in https://github.com/astral-sh/uv/pull/8263 and
https://github.com/astral-sh/uv/pull/8463, which were originally merged
into the v0.5 tracking branch but can now be committed separately, as
we've made `.env` loading opt-in.

In summary:

- `.env` loading is now opt-in (`--env-file .env`).
- `.env` remains supported on `uv run`, so it's meant for providing
environment variables to the run command, rather than to uv itself.

---------

Co-authored-by: Eduardo González Vaquero <47718648+edugzlez@users.noreply.github.com>

docs/configuration/environment.md

@@ -174,3 +174,5 @@ uv respects the following environment variables:
   For example, `RUST_LOG=trace` will enable trace-level logging.
   See the [tracing documentation](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#example-syntax)
   for more.
+- <a id="UV_ENV_FILE"></a> [`UV_ENV_FILE`](#UV_ENV_FILE): `.env` files from which to load environment variables when executing `uv run` commands.
+- <a id="UV_NO_ENV_FILE"></a> [`UV_NO_ENV_FILE`](#UV_NO_ENV_FILE): Ignore `.env` files when executing `uv run` commands.

docs/configuration/files.md

@@ -72,6 +72,31 @@ configuration files (e.g., user-level configuration will be ignored).
 
 See the [settings reference](../reference/settings.md) for an enumeration of the available settings.
 
+## `.env`
+
+`uv run` can load environment variables from dotenv files (e.g., `.env`, `.env.local`,
+`.env.development`), powered by the [`dotenvy`](https://github.com/allan2/dotenvy) crate.
+
+To load a `.env` file from a dedicated location, set the `UV_ENV_FILE` environment variable, or pass
+the `--env-file` flag to `uv run`.
+
+For example, to load environment variables from a `.env` file in the current working directory:
+
+```console
+$ uv run --env-file .env -- echo $MY_ENV_VAR
+```
+
+The `--env-file` flag can be provided multiple times, with subsequent files overriding values
+defined in previous files. To provide multiple files via the `UV_ENV_FILE` environment variable,
+separate the paths with a space (e.g., `UV_ENV_FILE="/path/to/file1 /path/to/file2"`).
+
+To disable dotenv loading (e.g., to override `UV_ENV_FILE` or the `--env-file` command-line
+argument), set the `UV_NO_ENV_FILE` environment variable to `1`, or pass the`--no-env-file` flag to
+`uv run`.
+
+If the same variable is defined in the environment and in a `.env` file, the value from the
+environment will take precedence.
+
 ## Configuring the pip interface
 
 A dedicated [`[tool.uv.pip]`](../reference/settings.md#pip) section is provided for configuring

docs/reference/cli.md

@@ -139,6 +139,11 @@ uv run [OPTIONS] [COMMAND]
 
 <p>See <code>--project</code> to only change the project root directory.</p>
 
+</dd><dt><code>--env-file</code> <i>env-file</i></dt><dd><p>Load environment variables from a <code>.env</code> file.</p>
+
+<p>Can be provided multiple times, with subsequent files overriding values defined in previous files.</p>
+
+<p>May also be set with the <code>UV_ENV_FILE</code> environment variable.</p>
 </dd><dt><code>--exclude-newer</code> <i>exclude-newer</i></dt><dd><p>Limit candidate packages to those that were uploaded prior to the given date.</p>
 
 <p>Accepts both RFC 3339 timestamps (e.g., <code>2006-12-02T02:07:43Z</code>) and local dates in the same format (e.g., <code>2006-12-02</code>) in your system&#8217;s configured time zone.</p>
@@ -296,6 +301,9 @@ uv run [OPTIONS] [COMMAND]
 
 </dd><dt><code>--no-editable</code></dt><dd><p>Install any editable dependencies, including the project and any workspace members, as non-editable</p>
 
+</dd><dt><code>--no-env-file</code></dt><dd><p>Avoid reading environment variables from a <code>.env</code> file</p>
+
+<p>May also be set with the <code>UV_NO_ENV_FILE</code> environment variable.</p>
 </dd><dt><code>--no-group</code> <i>no-group</i></dt><dd><p>Exclude dependencies from the specified dependency group.</p>
 
 <p>May be provided multiple times.</p>