|
| 1 | +# uv |
| 2 | + |
| 3 | +## Recommended Usage |
| 4 | + |
| 5 | +The recommended way to run [uv](https://docs.astral.sh/uv/) using Trunk is to use the SYSTEM |
| 6 | +environment, rather than a hermetic setup. This is because uv provides its own environment |
| 7 | +management that will often collide with Trunk's hermetic setup. Nevertheless, leveraging uv and |
| 8 | +Trunk in parallel can be powerful. |
| 9 | + |
| 10 | +Trunk provides several different Actions for running your uv validation and dependency management. |
| 11 | + |
| 12 | +| action | description | |
| 13 | +| ---------- | ------------------------------------------------------------------------------ | |
| 14 | +| `uv-check` | Validate `pyproject.toml` when running `git commit` | |
| 15 | +| `uv-lock` | Create or update `uv.lock` when running `git commit` | |
| 16 | +| `uv-sync` | Install dependencies from `uv.lock` when running `git checkout` or `git merge` | |
| 17 | + |
| 18 | +You can enable any subset of these Actions using `trunk actions enable`. |
| 19 | + |
| 20 | +As written, all of these actions require that you have `uv` in your `PATH` in order to run. |
| 21 | + |
| 22 | +## Hermetic Installation |
| 23 | + |
| 24 | +Trunk provides some mechanisms for a hermetic installation and execution of `uv`. You can use the uv |
| 25 | +[Tool](https://docs.trunk.io/check/advanced-setup/tools) to run `uv` manually, and you can override |
| 26 | +each of the action definitions to include the `packages_file` and `runtime`, like so: |
| 27 | + |
| 28 | +```yaml |
| 29 | +version: 0.1 |
| 30 | +actions: |
| 31 | + definitions: |
| 32 | + - id: uv-check |
| 33 | + runtime: python |
| 34 | + packages_file: ${cwd}/requirements.txt |
| 35 | +``` |
| 36 | +
|
| 37 | +These overrides will tell Trunk to use the hermetic install of `uv` and use a sandboxed execution |
| 38 | +for the Action. Note that this approach has some limitations, namely when creating uv virtual |
| 39 | +environments. Currently full functionality is blocked by the inability to unset runtime-inherited |
| 40 | +environments. Note that the `uv` Tool suffers from the same problem. |
| 41 | + |
| 42 | +When using the hermetic installation, you will want to ensure that your `python` runtime is enabled |
| 43 | +at the same version required by your uv configuration. See our |
| 44 | +[docs](https://docs.trunk.io/check/advanced-setup/runtimes) for more information about specifying |
| 45 | +runtime versions. |
| 46 | + |
| 47 | +## Notes |
| 48 | + |
| 49 | +uv requires Python 3.8 or higher to run. |
0 commit comments