docs: Add uv guide#932
Open
vdusek wants to merge 4 commits into
Open
Conversation
Add a new guide on managing Actor projects with the uv package manager, covering project setup, local development with the Apify CLI, the uv-based Dockerfile, deployment, and dependency management.
vdusek
added
adhoc
vdusek
added
adhoc
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #932 +/- ##
==========================================
- Coverage 86.94% 86.87% -0.07%
==========================================
Files 48 48
Lines 2942 2942
==========================================
- Hits 2558 2556 -2
- Misses 384 386 +2
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
…n uv guide The scaffolding section referenced a Dockerfile that is only created later in the guide, which was confusing without a pointer. The local run example also used the optional --purge flag, which is not needed for the tutorial flow.
"Use uv" was too terse - unlike the scraping-library guides, the tool name alone does not convey the guide's purpose. The new title mirrors the guide's intro sentence and the verb-first sidebar convention.
Contributor
Author
Mantisus
reviewed
Jun 3, 2026
| # layer. The cache mount speeds up repeated builds, and the bind mounts make the | ||
| # project metadata available without copying it into the image. This layer is | ||
| # rebuilt only when uv.lock or pyproject.toml change - not on source code edits. | ||
| RUN --mount=type=cache,target=/root/.cache/uv \ |
Collaborator
There was a problem hiding this comment.
Have you tested it on the platform?
A few months ago, the --mount= options weren't supported for building containers on the platform.
The guide pointed readers to a python-uv template that isn't published. An info banner now explains templates are pip-only for now and links the tracking issue apify/actor-templates#350.
Mantisus
reviewed
Jun 3, 2026
|
|
||
| - The lockfile guarantees that the dependencies installed in the Actor's Docker image are exactly the ones you developed and tested against locally. | ||
| - Dependency installation during the Docker build is significantly faster than with pip, especially with a warm cache. | ||
| - A single tool manages your Python interpreter, virtual environment, and dependencies, so the project works the same on every machine. |
Collaborator
There was a problem hiding this comment.
NIT.
In the example Dockerfile, we don't use uv to manage the Python interpreter; instead, we call the system Python.
| └── uv.lock | ||
| ``` | ||
|
|
||
| Make sure to commit `uv.lock` and `.python-version` to version control, so that every machine - and the Actor's Docker build - works with identical dependencies and Python version. |
Collaborator
There was a problem hiding this comment.
uv doesn't install Python with UV_PYTHON_DOWNLOADS=0, so .python-version and the associated text are irrelevant.
| [tool.uv] | ||
| # The Actor runs straight from the source tree as a module. uv only manages | ||
| # its dependencies, the project itself is not built and installed as a package. | ||
| package = false |
Collaborator
There was a problem hiding this comment.
Is this really necessary if build-system isn't defined?
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Adds a new "Manage your project with uv" guide to the Guides section - a tutorial covering the whole Actor lifecycle with the uv package and project manager: creating a project, the Actor scaffolding, running locally, installing the locked dependencies in the Dockerfile, deploying, and day-to-day dependency management.
The backing example project lives in
docs/03_guides/code/uv_project/, is covered by the repo lint and type checks, and the documented flow was verified end to end (localapify run+ a real Docker build/run).Since the Actor templates are pip-only for now, the guide carries an info banner pointing to apify/actor-templates#350. Companion template PR: apify/actor-templates#800.
TODO before merging
docs/03_guides/08_uv.mdx+docs/03_guides/code/uv_project/) towebsite/versioned_docs/version-3.4/as well, so it shows up in the current docs version and not only under "next".🤖 Generated with Claude Code