Skip to content

Commit 0426a58

Browse files
vdusekvdusek
committed
docs: Add uv guide
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.
1 parent b7ba52d commit 0426a58

7 files changed

Lines changed: 246 additions & 0 deletions

File tree

‎docs/01_introduction/quick-start.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -106,3 +106,4 @@ To see how you can integrate the Apify SDK with popular web scraping libraries,
106106
- [Crawlee](../guides/crawlee)
107107
- [Scrapy](../guides/scrapy)
108108
- [Running webserver](../guides/running-webserver)
109+
- [uv](../guides/uv)

‎docs/03_guides/08_uv.mdx‎

Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
---
2+
id: uv
3+
title: Use uv
4+
description: Manage your Actor's Python version, dependencies, and virtual environment with the uv package and project manager.
5+
---
6+
7+
import CodeBlock from '@theme/CodeBlock';
8+
import Tabs from '@theme/Tabs';
9+
import TabItem from '@theme/TabItem';
10+
11+
import PyprojectExample from '!!raw-loader!./code/uv_project/pyproject.toml';
12+
import MainExample from '!!raw-loader!./code/uv_project/my_actor/main.py';
13+
import UnderscoreMainExample from '!!raw-loader!./code/uv_project/my_actor/__main__.py';
14+
import DockerfileExample from '!!raw-loader!./code/uv_project/Dockerfile';
15+
16+
In this guide, you'll learn how to use [uv](https://docs.astral.sh/uv/) to manage your Apify Actor projects - from creating a new project, through running it locally, to building and deploying it on the Apify platform.
17+
18+
## Introduction
19+
20+
[uv](https://docs.astral.sh/uv/) is an extremely fast Python package and project manager. It replaces the combination of pip, virtualenv, and similar tools with a single binary that manages your project's Python version, virtual environment, and dependencies. It records the project metadata in the standard [`pyproject.toml`](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/) file and the exact resolved versions of all dependencies in a [`uv.lock`](https://docs.astral.sh/uv/concepts/projects/sync/) lockfile.
21+
22+
The [Python Actor templates](https://apify.com/templates/categories/python) declare their dependencies in a `requirements.txt` file, which is the default approach for Actors. Using uv instead brings a few advantages:
23+
24+
- The lockfile guarantees that the dependencies installed in the Actor's Docker image are exactly the ones you developed and tested against locally.
25+
- Dependency installation during the Docker build is significantly faster than with pip, especially with a warm cache.
26+
- A single tool manages your Python interpreter, virtual environment, and dependencies, so the project works the same on every machine.
27+
28+
To follow along, install [uv](https://docs.astral.sh/uv/getting-started/installation/) and the [Apify CLI](https://docs.apify.com/cli/docs/installation) first. If you prefer to start from a ready-made project instead of setting one up step by step, use the [uv Actor template](https://apify.com/templates/python-uv).
29+
30+
## Create a new project
31+
32+
Create a new uv project and add the Apify SDK to its dependencies:
33+
34+
```bash
35+
uv init my-actor --bare
36+
cd my-actor
37+
uv python pin 3.14
38+
uv add apify
39+
```
40+
41+
The [`uv init`](https://docs.astral.sh/uv/reference/cli/#uv-init) command with the `--bare` option creates just the `pyproject.toml` project manifest. The `uv python pin` command writes the project's Python version to the `.python-version` file - uv automatically downloads that Python version if it's not installed on your machine. Finally, [`uv add`](https://docs.astral.sh/uv/reference/cli/#uv-add) records the dependency in `pyproject.toml`, resolves the exact versions of the whole dependency tree into `uv.lock`, and installs everything into the project's virtual environment in `.venv`.
42+
43+
The `uv add` command constrains the dependency to the latest version it resolved. You can edit the constraint as you see fit - this guide's example Actor allows any version of the SDK within the current major one:
44+
45+
<CodeBlock className="language-toml" title="pyproject.toml">
46+
{PyprojectExample}
47+
</CodeBlock>
48+
49+
The `package = false` setting in the `[tool.uv]` section tells uv that the project is not a Python package that needs to be built and installed - the Actor just runs as a module straight from the source tree, and uv only manages its dependencies.
50+
51+
## Add the Actor scaffolding
52+
53+
For the project to be runnable as an Actor, it needs two more pieces: the source code as a runnable Python package, and the `.actor/` directory with the [Actor configuration](https://docs.apify.com/platform/actors/development/actor-definition/actor-json).
54+
55+
Create a `my_actor` package with the Actor's source code:
56+
57+
<Tabs>
58+
<TabItem value="my_actor/main.py" label="my_actor/main.py" default>
59+
<CodeBlock className="language-python">
60+
{MainExample}
61+
</CodeBlock>
62+
</TabItem>
63+
<TabItem value="my_actor/__main__.py" label="my_actor/__main__.py">
64+
<CodeBlock className="language-python">
65+
{UnderscoreMainExample}
66+
</CodeBlock>
67+
</TabItem>
68+
</Tabs>
69+
70+
Don't forget to add an empty `my_actor/__init__.py` file, so that the directory is a regular Python package executable with `python -m my_actor`.
71+
72+
Then add the Actor definition to `.actor/actor.json`:
73+
74+
```json title=".actor/actor.json"
75+
{
76+
"$schema": "https://apify.com/schemas/v1/actor.ide.json",
77+
"actorSpecification": 1,
78+
"name": "my-actor",
79+
"title": "My uv Actor",
80+
"description": "An Apify Actor with dependencies managed by uv.",
81+
"version": "0.1",
82+
"buildTag": "latest",
83+
"dockerfile": "../Dockerfile"
84+
}
85+
```
86+
87+
The final project structure looks like this:
88+
89+
```text
90+
my-actor/
91+
├── .actor/
92+
│ └── actor.json
93+
├── my_actor/
94+
│ ├── __init__.py
95+
│ ├── __main__.py
96+
│ └── main.py
97+
├── .python-version
98+
├── Dockerfile
99+
├── pyproject.toml
100+
└── uv.lock
101+
```
102+
103+
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.
104+
105+
## Run the Actor locally
106+
107+
If you've just cloned the project (or skipped `uv add` above), install the dependencies first:
108+
109+
```bash
110+
uv sync
111+
```
112+
113+
The [`uv sync`](https://docs.astral.sh/uv/reference/cli/#uv-sync) command creates the `.venv` virtual environment (if it doesn't exist yet) and installs the locked dependencies into it. Then run the Actor with the Apify CLI:
114+
115+
```bash
116+
apify run --purge
117+
```
118+
119+
The [`apify run`](https://docs.apify.com/cli/docs/reference#apify-run) command automatically detects the virtual environment in `.venv` and uses it to run the Actor as a module (`python -m my_actor`), with the environment set up to emulate the Apify platform locally - for example, the Actor input is read from `storage/key_value_stores/default/INPUT.json`.
120+
121+
## Use uv in the Dockerfile
122+
123+
On the Apify platform, the Actor runs as a Docker container built from the Dockerfile referenced in `.actor/actor.json`. The following Dockerfile installs the locked dependencies with uv on top of the [Apify Python base image](https://hub.docker.com/r/apify/actor-python):
124+
125+
<CodeBlock className="language-docker" title="Dockerfile">
126+
{DockerfileExample}
127+
</CodeBlock>
128+
129+
A few details worth understanding:
130+
131+
- The uv binary is copied from its [official Docker image](https://docs.astral.sh/uv/guides/integration/docker/), pinned to a minor version line, so builds are reproducible and there is no need to install uv with pip.
132+
- `uv sync --locked --no-dev` installs the dependencies exactly as recorded in `uv.lock` and skips development dependencies. If the lockfile is missing or out of sync with `pyproject.toml`, the build fails instead of silently resolving different versions.
133+
- The dependencies are installed in a separate layer before the source code is copied, so editing your code doesn't invalidate the dependency layer, and rebuilds are fast.
134+
- Putting `.venv/bin` first on `PATH` makes `python` resolve to the project's virtual environment, both during the build and when the Actor runs.
135+
136+
Also create a `.dockerignore` file and exclude at least `.venv`, `.git`, and `storage` from the Docker build context - the local virtual environment must never be copied into the image, since it's recreated by `uv sync` during the build.
137+
138+
## Deploy to the Apify platform
139+
140+
Once the Actor works locally, log in and push it to the Apify platform:
141+
142+
```bash
143+
apify login
144+
apify push
145+
```
146+
147+
The [`apify push`](https://docs.apify.com/cli/docs/reference#apify-push) command uploads the project to the platform and builds the Docker image from the Dockerfile above. Thanks to the committed lockfile, the platform build installs exactly the dependency versions you ran locally.
148+
149+
## Manage dependencies
150+
151+
Day-to-day dependency management goes through uv as well:
152+
153+
```bash
154+
# Add a dependency (records it in pyproject.toml and updates uv.lock).
155+
uv add httpx
156+
157+
# Add a development-only dependency (skipped in the Docker build by --no-dev).
158+
uv add --dev ruff
159+
160+
# Remove a dependency.
161+
uv remove httpx
162+
163+
# Upgrade all dependencies to the latest versions allowed by pyproject.toml.
164+
uv lock --upgrade
165+
uv sync
166+
```
167+
168+
Whenever the dependencies change, commit the updated `uv.lock` together with `pyproject.toml`.
169+
170+
## Conclusion
171+
172+
In this guide, you learned how to use uv to manage Apify Actor projects. You can now create a uv project with the Apify SDK, run it locally with the Apify CLI, install the locked dependencies with uv in the Actor's Docker image, and deploy the whole project to the Apify platform with reproducible builds. If you have questions or need assistance, feel free to reach out on our [GitHub](https://github.com/apify/apify-sdk-python) or join our [Discord community](https://discord.com/invite/jyEM2PRvMU). Happy coding!
173+
174+
## Additional resources
175+
176+
- [uv: Official documentation](https://docs.astral.sh/uv/)
177+
- [uv: Working on projects](https://docs.astral.sh/uv/guides/projects/)
178+
- [uv: Using uv in Docker](https://docs.astral.sh/uv/guides/integration/docker/)
179+
- [Apify: Actor Dockerfile documentation](https://docs.apify.com/platform/actors/development/actor-definition/dockerfile)
180+
- [Apify templates: Python](https://apify.com/templates/categories/python)

‎docs/03_guides/code/uv_project/Dockerfile‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# syntax=docker/dockerfile:1
2+
# First, specify the base Docker image.
3+
# You can see the Docker images from Apify at https://hub.docker.com/r/apify/.
4+
# You can also use any other image from Docker Hub.
5+
FROM apify/actor-python:3.14
6+
7+
# Add the uv binary from its official distroless image (pinned to the 0.11.x line).
8+
COPY --from=ghcr.io/astral-sh/uv:0.11 /uv /uvx /bin/
9+
10+
# Configure uv for container builds:
11+
# - compile installed packages to bytecode, so the Actor starts faster,
12+
# - copy packages instead of hardlinking, which avoids warnings with the cache mount,
13+
# - never download a managed Python, always reuse the base image's interpreter,
14+
# - put the project virtual environment first on PATH, so `python` resolves to it.
15+
ENV UV_COMPILE_BYTECODE=1 \
16+
UV_LINK_MODE=copy \
17+
UV_PYTHON_DOWNLOADS=0 \
18+
PATH="/usr/src/app/.venv/bin:$PATH"
19+
20+
# Install dependencies into the project virtual environment (.venv) as a separate
21+
# layer. The cache mount speeds up repeated builds, and the bind mounts make the
22+
# project metadata available without copying it into the image. This layer is
23+
# rebuilt only when uv.lock or pyproject.toml change - not on source code edits.
24+
RUN --mount=type=cache,target=/root/.cache/uv \
25+
--mount=type=bind,source=uv.lock,target=uv.lock \
26+
--mount=type=bind,source=pyproject.toml,target=pyproject.toml \
27+
uv sync --locked --no-dev
28+
29+
# Next, copy the remaining files and directories with the source code.
30+
# Since we do this after installing the dependencies, quick rebuilds will be
31+
# really fast for most source file changes.
32+
COPY . ./
33+
34+
# Use compileall to ensure the runnability of the Actor Python code.
35+
RUN python -m compileall -q my_actor/
36+
37+
# Specify how to launch the source code of your Actor.
38+
CMD ["python", "-m", "my_actor"]

‎docs/03_guides/code/uv_project/my_actor/__init__.py‎

Whitespace-only changes.

‎docs/03_guides/code/uv_project/my_actor/__main__.py‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
import asyncio
2+
3+
from .main import main
4+
5+
if __name__ == '__main__':
6+
asyncio.run(main())

‎docs/03_guides/code/uv_project/my_actor/main.py‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
from apify import Actor
2+
3+
4+
async def main() -> None:
5+
async with Actor:
6+
actor_input = await Actor.get_input() or {}
7+
Actor.log.info('Actor input: %s', actor_input)
8+
await Actor.set_value('OUTPUT', 'Hello from a uv-managed Actor!')

‎docs/03_guides/code/uv_project/pyproject.toml‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
[project]
2+
name = "my-actor"
3+
version = "0.1.0"
4+
description = "An Apify Actor with dependencies managed by uv."
5+
requires-python = ">=3.14"
6+
dependencies = [
7+
"apify>=3.0.0,<4.0.0",
8+
]
9+
10+
[tool.uv]
11+
# The Actor runs straight from the source tree as a module. uv only manages
12+
# its dependencies, the project itself is not built and installed as a package.
13+
package = false

0 commit comments

Comments
 (0)