setup-uv/docs/environment-and-tools.md

# Environment and Tools

This document covers environment activation, tool directory configuration, and authentication options.

## Activate environment

You can set `activate-environment` to `true` to automatically activate a venv.
This allows directly using it in later steps:

```yaml
- name: Install the latest version of uv and activate the environment
  uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
  with:
    activate-environment: true
- run: uv pip install pip
```

By default, the venv is created at `.venv` inside the `working-directory`.

With `activate-environment: true`, the `python-runtime-id` output identifies the
venv's Python runtime as reported by uv. This is an opaque identifier that users of the action
can use as a cache key if necessary; users should not assume anything about
the stability or structure of the identifier itself.

For example, you can combine it with the platform and dependency information relevant to
your cache with `id: setup-uv` on the setup step:

```yaml
key: build-${{ runner.os }}-${{ runner.arch }}-${{ steps.setup-uv.outputs.python-runtime-id }}-${{ hashFiles('uv.lock') }}
```

You can customize the venv location with `venv-path`, for example to place it in the runner temp directory:

```yaml
- uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
  with:
    activate-environment: true
    venv-path: ${{ runner.temp }}/custom-venv
```

> [!WARNING]
>
> Activating the environment adds your dependencies to the `PATH`, which could break some workflows.
> For example, if you have a dependency which requires uv, e.g., `hatch`, activating the
> environment will shadow the `uv` binary installed by this action and may result in a different uv
> version being used.
>
> We do not recommend using this setting for most use-cases. Instead, use `uv run` to execute
> commands in the environment.

## GitHub authentication token

By default, this action resolves available uv versions from
[`astral-sh/versions`](https://github.com/astral-sh/versions), then downloads uv artifacts from
GitHub Releases.

You can provide a token via `github-token` to authenticate those downloads. By default, the
`GITHUB_TOKEN` secret is used, which is automatically provided by GitHub Actions.

If the default
[permissions for the GitHub token](https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication#permissions-for-the-github_token)
are not sufficient, you can provide a custom GitHub token with the necessary permissions.

```yaml
- name: Install the latest version of uv with a custom GitHub token
  uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
  with:
    github-token: ${{ secrets.CUSTOM_GITHUB_TOKEN }}
```

## UV_TOOL_DIR

On Windows `UV_TOOL_DIR` is set to `uv-tool-dir` in the `TMP` dir (e.g. `D:\a\_temp\uv-tool-dir`).
On GitHub hosted runners this is on the much faster `D:` drive.

On all other platforms the tool environments are placed in the
[default location](https://docs.astral.sh/uv/concepts/tools/#tools-directory).

If you want to change this behaviour (especially on self-hosted runners) you can use the `tool-dir`
input:

```yaml
- name: Install the latest version of uv with a custom tool dir
  uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
  with:
    tool-dir: "/path/to/tool/dir"
```

## UV_TOOL_BIN_DIR

On Windows `UV_TOOL_BIN_DIR` is set to `uv-tool-bin-dir` in the `TMP` dir (e.g.
`D:\a\_temp\uv-tool-bin-dir`). On GitHub hosted runners this is on the much faster `D:` drive. This
path is also automatically added to the PATH.

On all other platforms the tool binaries get installed to the
[default location](https://docs.astral.sh/uv/concepts/tools/#the-bin-directory).

If you want to change this behaviour (especially on self-hosted runners) you can use the
`tool-bin-dir` input:

```yaml
- name: Install the latest version of uv with a custom tool bin dir
  uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
  with:
    tool-bin-dir: "/path/to/tool-bin/dir"
```

## Tilde Expansion

This action supports expanding the `~` character to the user's home directory for the following inputs:

- `version-file`
- `cache-local-path`
- `tool-dir`
- `tool-bin-dir`
- `cache-dependency-glob`

```yaml
- name: Expand the tilde character
  uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
  with:
    cache-local-path: "~/path/to/cache"
    tool-dir: "~/path/to/tool/dir"
    tool-bin-dir: "~/path/to/tool-bin/dir"
    cache-dependency-glob: "~/my-cache-buster"
```

## Ignore empty workdir

By default, the action will warn if the workdir is empty, because this is usually the case when
`actions/checkout` is configured to run after `setup-uv`, which is not supported.

If you want to ignore this, set the `ignore-empty-workdir` input to `true`.

```yaml
- name: Ignore empty workdir
  uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
  with:
    ignore-empty-workdir: true
```

## Environment Variables

This action sets several environment variables that influence uv's behavior and can be used by subsequent steps:

- `UV_PYTHON`: Set when `python-version` is specified or the selected `.tool-versions` file contains a supported `python` entry. Controls which Python version uv uses.
- `UV_CACHE_DIR`: Set when caching is enabled (unless already configured in uv config files). Controls where uv stores its cache.
- `UV_TOOL_DIR`: Set when `tool-dir` input is specified. Controls where uv installs tool environments.
- `UV_TOOL_BIN_DIR`: Set when `tool-bin-dir` input is specified. Controls where uv installs tool binaries.
- `UV_PYTHON_INSTALL_DIR`: Always set. Controls where uv installs Python versions.
- `VIRTUAL_ENV`: Set when `activate-environment` is true. Points to the activated virtual environment.

**Environment variables that affect the action behavior:**

- `UV_NO_MODIFY_PATH`: If set, prevents the action from modifying PATH. Cannot be used with `activate-environment`.
- `UV_CACHE_DIR`: If already set, the action will respect it instead of setting its own cache directory.
- `UV_PYTHON`: If already set and `python-version` is not specified, the action will respect it instead of using the `python` entry from `.tool-versions`.

```yaml
- name: Example using environment variables
  uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
  with:
    python-version: "3.12"
    tool-dir: "/custom/tool/dir"
    enable-cache: true

- name: Check environment variables
  run: |
    echo "UV_PYTHON: $UV_PYTHON"
    echo "UV_CACHE_DIR: $UV_CACHE_DIR"
    echo "UV_TOOL_DIR: $UV_TOOL_DIR"
    echo "UV_PYTHON_INSTALL_DIR: $UV_PYTHON_INSTALL_DIR"
```