Add Coiled integration doc page by jrbourbeau · Pull Request #14430 · astral-sh/uv

jrbourbeau · 2025-07-02T19:53:08Z

This PR adds a new integrations doc page for using uv with Coiled. It's a slightly adapted version of this blog post https://docs.coiled.io/blog/uv-coiled-cloud-scripts.html

Side note: it's been really pleasant using uv and Coiled together recently

cc @zanieb for visibility

zanieb · 2025-07-09T15:53:32Z

docs/guides/integration/coiled.md

+could be _any_ Python code.
+
+Running this script requires `pandas`, `pyarrow`, and `s3fs`. uv makes it easy to embed these
+dependencies directly in the script using [PEP 273](https://peps.python.org/pep-0723/) inline


Suggested change

dependencies directly in the script using [PEP 273](https://peps.python.org/pep-0723/) inline

dependencies directly in the script using [PEP 723](https://peps.python.org/pep-0723/) inline

docs/guides/integration/coiled.md

zanieb

I think I need to do a pass on this to make the language / tone consistent with the rest of the documentation, so feel free to just leave those minor changes.

jrbourbeau · 2025-07-09T15:58:45Z

I think I need to do a pass on this to make the language / tone consistent with the rest of the documentation, so feel free to just leave those minor changes.

Sounds good, thanks for reviewing. Happy to iterate as needed

zanieb · 2025-08-01T13:19:47Z

docs/guides/integration/coiled.md

+To learn more about using inline script metadata with uv, see the
+[script guide](../scripts.md#declaring-script-dependencies).


I didn't want to duplicate too much detail on using scripts with inline metadata. I'm hoping we can direct people to the official guide if they want more on that.

zanieb · 2025-08-01T13:21:40Z

docs/guides/integration/coiled.md

+<!-- TODO
+This command returns immediately, it doesn't wait for the job to finish and it doesn't seem
+like there's a flag for that. It also doesn't happen much faster, because a remote job needs to
+spawn. I also wasn't sure how to get the logs for the job. I eventually found it with
+`uvx coiled batch logs 1067394`. I also tried `uvx coiled batch wait 1067394`, but it didn't have
+an option to show logs and that retrieving the id in the first place was a bit challenging, e.g.,
+`uvx coiled batch status` shows it as a cluster ID at the top but that's not obvious.
+
+I presume some of these problems are because this API is designed around running multiple batch
+jobs, however, if the user experience for running the script locally is that it waits for execution
+and shows the output, then we need to address that difference in user experience here.
+
+It looks like `uvx coiled batch run -- uv run process.py` isn't supported (using the `--` as a
+separator), I wanted to use that for a single-line commmand that still separated the `uv run`
+command.
+-->


@jrbourbeau Let's talk about this bit and what we can do to clarify this or improve on the experience?

(I don't really expect you to go change things in Coiled in service of this goal, but I was pretty confused about what was happening and I'm an advanced user, so we need to say more at least)

I also wasn't sure how to get the logs for the job. I eventually found it with
uvx coiled batch logs 1067394.

Yeah, that's exactly where to go for getting logs programatically. The other, less programatic, way is to look at logs in the Coiled UI. We output the link to view the batch job in the Coiled UI in the terminal output from coiled batch run

if the user experience for running the script locally is that it waits for execution
and shows the output, then we need to address that difference in user experience here

That's a fair point. I went ahead an made a small update here 109a099 that hopefully helps address this. Let me know what you think -- happy to update again

It looks like uvx coiled batch run -- uv run process.py isn't supported (using the -- as a
separator), I wanted to use that for a single-line command that still separated the uv run
command.

Hmm that's supposed to work and I'm not able to reproduce an issue -- what error are you seeing?

zanieb · 2025-08-01T13:23:11Z

@jrbourbeau I made quite a few edits, please let me know if you have qualms with anything! Thanks for your patience.

This MR contains the following updates: | Package | Update | Change | |---|---|---| | [astral-sh/uv](https://github.com/astral-sh/uv) | patch | `0.8.17` -> `0.8.22` | MR created with the help of [el-capitano/tools/renovate-bot](https://gitlab.com/el-capitano/tools/renovate-bot). **Proposed changes to behavior should be submitted there as MRs.** --- ### Release Notes <details> <summary>astral-sh/uv (astral-sh/uv)</summary> ### [`v0.8.22`](https://github.com/astral-sh/uv/blob/HEAD/CHANGELOG.md#0822) [Compare Source](astral-sh/uv@0.8.21...0.8.22) Released on 2025-09-23. ##### Python - Upgrade Pyodide to 0.28.3 ([#15999](astral-sh/uv#15999)) ##### Security - Upgrade `astral-tokio-tar` to 0.5.5 which [hardens tar archive extraction](GHSA-3wgq-wrwc-vqmv) ([#16004](astral-sh/uv#16004)) ### [`v0.8.21`](https://github.com/astral-sh/uv/blob/HEAD/CHANGELOG.md#0821) [Compare Source](astral-sh/uv@0.8.20...0.8.21) Released on 2025-09-23. ##### Enhancements - Refresh lockfile when `--refresh` is provided ([#15994](astral-sh/uv#15994)) ##### Preview features Add support for S3 request signing ([#15925](astral-sh/uv#15925)) ### [`v0.8.20`](https://github.com/astral-sh/uv/blob/HEAD/CHANGELOG.md#0820) [Compare Source](astral-sh/uv@0.8.19...0.8.20) Released on 2025-09-22. ##### Enhancements - Add `--force` flag for `uv cache clean` ([#15992](astral-sh/uv#15992)) - Improve resolution errors with proxied packages ([#15200](astral-sh/uv#15200)) ##### Preview features - Allow upgrading pre-release versions of the same minor Python version ([#15959](astral-sh/uv#15959)) ##### Bug fixes - Hide `freethreaded+debug` Python downloads in `uv python list` ([#15985](astral-sh/uv#15985)) - Retain the cache lock and temporary caches during `uv run` and `uvx` ([#15990](astral-sh/uv#15990)) ##### Documentation - Add `package` level conflicts to the conflicting dependencies docs ([#15963](astral-sh/uv#15963)) - Document pyodide support ([#15962](astral-sh/uv#15962)) - Document support for free-threaded and debug Python versions ([#15961](astral-sh/uv#15961)) - Expand the contribution docs on issue selection ([#15966](astral-sh/uv#15966)) - Tweak title for viewing version in project guide ([#15964](astral-sh/uv#15964)) ### [`v0.8.19`](https://github.com/astral-sh/uv/blob/HEAD/CHANGELOG.md#0819) [Compare Source](astral-sh/uv@0.8.18...0.8.19) Released on 2025-09-19. ##### Python - Add CPython 3.14.0rc3 - Upgrade OpenSSL to 3.5.3 See the [python-build-standalone release notes](https://github.com/astral-sh/python-build-standalone/releases/tag/20250918) for more details. ##### Bug fixes - Make `uv cache clean` parallel process safe ([#15888](astral-sh/uv#15888)) - Fix implied `platform_machine` marker for `win_arm64` platform tag ([#15921](astral-sh/uv#15921)) ### [`v0.8.18`](https://github.com/astral-sh/uv/blob/HEAD/CHANGELOG.md#0818) [Compare Source](astral-sh/uv@0.8.17...0.8.18) Released on 2025-09-17. ##### Enhancements - Add PyG packages to torch backend ([#15911](astral-sh/uv#15911)) - Add handling for unnamed conda environments in base environment detection ([#15681](astral-sh/uv#15681)) - Allow selection of debug build interpreters ([#11520](astral-sh/uv#11520)) - Improve `uv init` defaults for native build backend cache keys ([#15705](astral-sh/uv#15705)) - Error when `pyproject.toml` target does not exist for dependency groups ([#15831](astral-sh/uv#15831)) - Infer check URL from publish URL when known ([#15886](astral-sh/uv#15886)) - Support Gitlab CI/CD as a trusted publisher ([#15583](astral-sh/uv#15583)) - Add GraalPy 25.0.0 with support for Python 3.12 ([#15900](astral-sh/uv#15900)) - Add `--no-clear` to `uv venv` to disable removal prompts ([#15795](astral-sh/uv#15795)) - Add conflict detection between `--only-group` and `--extra` flags ([#15788](astral-sh/uv#15788)) - Allow `[project]` to be missing from a `pyproject.toml` ([#14113](astral-sh/uv#14113)) - Always treat conda environments named `base` and `root` as base environments ([#15682](astral-sh/uv#15682)) - Improve log message when direct build for `uv_build` is skipped ([#15898](astral-sh/uv#15898)) - Log when the cache is disabled ([#15828](astral-sh/uv#15828)) - Show pyx organization name after authenticating ([#15823](astral-sh/uv#15823)) - Use `_CONDA_ROOT` to detect Conda base environments ([#15680](astral-sh/uv#15680)) - Include blake2b hash in `uv publish` upload form ([#15794](astral-sh/uv#15794)) - Fix misleading debug message when removing environments in `uv sync` ([#15881](astral-sh/uv#15881)) ##### Deprecations - Deprecate `tool.uv.dev-dependencies` ([#15469](astral-sh/uv#15469)) - Revert "feat(ci): build loongarch64 binaries in CI ([#15387](astral-sh/uv#15387))" ([#15820](astral-sh/uv#15820)) ##### Preview features - Propagate preview flag to client for `native-auth` feature ([#15872](astral-sh/uv#15872)) - Store native credentials for realms with the https scheme stripped ([#15879](astral-sh/uv#15879)) - Use the root index URL when retrieving credentials from the native store ([#15873](astral-sh/uv#15873)) ##### Bug fixes - Fix `uv sync --no-sources` not switching from editable to registry installations ([#15234](astral-sh/uv#15234)) - Avoid display of an empty string when a path is the working directory ([#15897](astral-sh/uv#15897)) - Allow cached environment reuse with `@latest` ([#15827](astral-sh/uv#15827)) - Allow escaping spaces in --env-file handling ([#15815](astral-sh/uv#15815)) - Avoid ANSI codes in debug! messages ([#15843](astral-sh/uv#15843)) - Improve BSD tag construction ([#15829](astral-sh/uv#15829)) - Include SHA when listing lockfile changes ([#15817](astral-sh/uv#15817)) - Invert the logic for determining if a path is a base conda environment ([#15679](astral-sh/uv#15679)) - Load credentials for explicit members when lowering ([#15844](astral-sh/uv#15844)) - Re-add `triton` as a torch backend package ([#15910](astral-sh/uv#15910)) - Respect `UV_INSECURE_NO_ZIP_VALIDATION=1` in duplicate header errors ([#15912](astral-sh/uv#15912)) ##### Documentation - Add GitHub Actions to PyPI trusted publishing example ([#15753](astral-sh/uv#15753)) - Add Coiled integration documentation ([#14430](astral-sh/uv#14430)) - Add verbose output to the getting help section ([#15915](astral-sh/uv#15915)) - Document `NO_PROXY` support ([#15816](astral-sh/uv#15816)) - Document cache-keys for native build backends ([#15811](astral-sh/uv#15811)) - Add documentation for dependency group `requires-python` ([#14282](astral-sh/uv#14282)) </details> --- ### Configuration 📅 **Schedule**: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined). 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻ **Rebasing**: Whenever MR becomes conflicted, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this MR and you won't be reminded about this update again. --- - [ ] If you want to rebase/retry this MR, check this box --- This MR has been generated by [Renovate Bot](https://github.com/renovatebot/renovate).

Add Coiled integration doc page

9ba5b24

zanieb self-assigned this Jul 2, 2025

Lint

f25c67e

zanieb reviewed Jul 9, 2025

View reviewed changes

docs/guides/integration/coiled.md Outdated Show resolved Hide resolved

zanieb reviewed Jul 9, 2025

View reviewed changes

docs/guides/integration/coiled.md Show resolved Hide resolved

zanieb reviewed Jul 9, 2025

View reviewed changes

docs/guides/integration/coiled.md Outdated Show resolved Hide resolved

zanieb reviewed Jul 9, 2025

View reviewed changes

Review

f5664c7

zanieb reviewed Aug 1, 2025

View reviewed changes

..

acaf097

zanieb reviewed Aug 1, 2025

View reviewed changes

fix typo

453122b

jrbourbeau and others added 3 commits August 18, 2025 14:33

Minor tweaks

653ea44

Update language to better reflect new user expectations

109a099

Edit again

9abf64f

zanieb enabled auto-merge (squash) September 12, 2025 12:13

zanieb merged commit 0b8117a into astral-sh:main Sep 12, 2025
98 checks passed

BrewTestBot mentioned this pull request Sep 17, 2025

uv 0.8.18 Homebrew/homebrew-core#244543

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Comments

Add Coiled integration doc page#14430

Add Coiled integration doc page#14430
zanieb merged 8 commits intoastral-sh:mainfrom
jrbourbeau:coiled-integration

jrbourbeau commented Jul 2, 2025

Uh oh!

zanieb Jul 9, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

zanieb left a comment

Uh oh!

jrbourbeau commented Jul 9, 2025

Uh oh!

zanieb Aug 1, 2025

Uh oh!

zanieb Aug 1, 2025

Uh oh!

zanieb Aug 1, 2025

Uh oh!

jrbourbeau Aug 20, 2025

Uh oh!

zanieb commented Aug 1, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	dependencies directly in the script using [PEP 273](https://peps.python.org/pep-0723/) inline
	dependencies directly in the script using [PEP 723](https://peps.python.org/pep-0723/) inline

		To learn more about using inline script metadata with uv, see the
		[script guide](../scripts.md#declaring-script-dependencies).

Comments

Conversation

jrbourbeau commented Jul 2, 2025

Uh oh!

zanieb Jul 9, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

zanieb left a comment

Choose a reason for hiding this comment

Uh oh!

jrbourbeau commented Jul 9, 2025

Uh oh!

zanieb Aug 1, 2025

Choose a reason for hiding this comment

Uh oh!

zanieb Aug 1, 2025

Choose a reason for hiding this comment

Uh oh!

zanieb Aug 1, 2025

Choose a reason for hiding this comment

Uh oh!

jrbourbeau Aug 20, 2025

Choose a reason for hiding this comment

Uh oh!

zanieb commented Aug 1, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants