Image

class

gworker_client.image.Image

Container image specification. Immutable — every method returns a new Image. Chains are evaluated top-to-bottom at deploy time to produce a Dockerfile. Share a base image across tasks to reuse the build cache.

Class

python
1class Image

Methods

base

python
1base(image: str = 'python:3.12-slim', python_version: str = '3.12') -> Image

Start a new image chain from a Docker Hub or registry image. python_version controls the Python interpreter used by pip_install steps.

pip_install

python
1pip_install(packages: str = ()) -> Image

Install one or more Python packages with pip. Accepts the same specifiers as pip install (name, name==version, git+url, etc.).

pip_install_requirements

python
1pip_install_requirements(path: str | Path) -> Image

Install packages listed in a requirements.txt file. The file is read at deploy time from the local filesystem relative to the project root.

pip_install_pyproject

python
1pip_install_pyproject(path: str | Path) -> Image

Install the package defined in a pyproject.toml. Equivalent to `pip install -e .` from the given path.

system_install

python
1system_install(packages: str = ()) -> Image

Install apt packages (Debian/Ubuntu base images only). Runs apt-get install -y without prompts.

run_commands

python
1run_commands(commands: str = ()) -> Image

Run arbitrary shell commands as root in the image build context. Each string is a separate RUN layer.

env

python
1env(vars: str = {}) -> Image

Set environment variables in the image (equivalent to Dockerfile ENV). Use for config that is not secret — for secrets, use Secret instead.

workdir

python
1workdir(path: str) -> Image

Set the working directory for subsequent commands and for the task at runtime. Equivalent to Dockerfile WORKDIR.

add_local_dir

python
1add_local_dir(local: str | Path, remote: str, ignore: Iterable[str] | None = None) -> Image

Copy a local directory into the image at remote. Patterns in ignore are excluded (gitignore syntax). The directory is snapshotted at deploy time.

add_local_file

python
1add_local_file(local: str | Path, remote: str) -> Image

Copy a single local file into the image at remote. The file is snapshotted at deploy time.

dockerfile_commands

python
1dockerfile_commands(commands: str = ()) -> Image

Append raw Dockerfile instructions verbatim. Use only for directives not covered by the other methods (e.g. LABEL, ARG, EXPOSE).

← Back to docs