Image

Package: flyte

This is a representation of Container Images, which can be used to create layered images programmatically.

Use by first calling one of the base constructor methods. These all begin with from or default_ The image can then be amended with additional layers using the various with_* methods.

Invariant for this class: The construction of Image objects must be doable everywhere. That is, if a user has a custom image that is not accessible, calling .with_source_file on a file that doesn’t exist, the instantiation of the object itself must still go through. Further, the .identifier property of the image must also still go through. This is because it may have been already built somewhere else. Use validate() functions to check each layer for actual errors. These are invoked at actual build time. See self.id for more information

class Image(
    base_image: Optional[str],
    dockerfile: Optional[Path],
    registry: Optional[str],
    name: Optional[str],
    platform: Tuple[Architecture, ...],
    python_version: Tuple[int, int],
    _ref_name: Optional[str],
    _layers: Tuple[Layer, ...],
    _image_registry_secret: Optional[Secret],
)

Methods

clone()

def clone(
    registry: Optional[str],
    registry_secret: Optional[str | Secret],
    name: Optional[str],
    base_image: Optional[str],
    python_version: Optional[Tuple[int, int]],
    addl_layer: Optional[Layer],
) -> Image

Use this method to clone the current image and change the registry and name

from_base()

def from_base(
    image_uri: str,
) -> Image

Use this method to start with a pre-built base image. This image must already exist in the registry of course.

from_debian_base()

def from_debian_base(
    python_version: Optional[Tuple[int, int]],
    flyte_version: Optional[str],
    install_flyte: bool,
    registry: Optional[str],
    registry_secret: Optional[str | Secret],
    name: Optional[str],
    platform: Optional[Tuple[Architecture, ...]],
) -> Image

Use this method to start using the default base image, built from this library’s base Dockerfile Default images are multi-arch amd/arm64

from_dockerfile()

def from_dockerfile(
    file: Path,
    registry: str,
    name: str,
    platform: Union[Architecture, Tuple[Architecture, ...], None],
) -> Image

Use this method to create a new image with the specified dockerfile. Note you cannot use additional layers after this, as the system doesn’t attempt to parse/understand the Dockerfile, and what kind of setup it has (python version, uv vs poetry, etc), so please put all logic into the dockerfile itself.

Also since Python sees paths as from the calling directory, please use Path objects with absolute paths. The context for the builder will be the directory where the dockerfile is located.

from_ref_name()

def from_ref_name(
    name: str,
) -> Image

from_uv_script()

def from_uv_script(
    script: Path | str,
    name: str,
    registry: str | None,
    registry_secret: Optional[str | Secret],
    python_version: Optional[Tuple[int, int]],
    index_url: Optional[str],
    extra_index_urls: Union[str, List[str], Tuple[str, ...], None],
    pre: bool,
    extra_args: Optional[str],
    platform: Optional[Tuple[Architecture, ...]],
    secret_mounts: Optional[SecretRequest],
) -> Image

Use this method to create a new image with the specified uv script. It uses the header of the script to determine the python version, dependencies to install. The script must be a valid uv script, otherwise an error will be raised.

Usually the header of the script will look like this: Example:

#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.12"
# dependencies = ["httpx"]
# ///

For more information on the uv script format, see the documentation: UV: Declaring script dependencies

validate()

def validate()

with_apt_packages()

def with_apt_packages(
    packages: str,
    secret_mounts: Optional[SecretRequest],
) -> Image

Use this method to create a new image with the specified apt packages layered on top of the current image

with_commands()

def with_commands(
    commands: List[str],
    secret_mounts: Optional[SecretRequest],
) -> Image

Use this method to create a new image with the specified commands layered on top of the current image Be sure not to use RUN in your command.

with_dockerignore()

def with_dockerignore(
    path: Path,
) -> Image

with_env_vars()

def with_env_vars(
    env_vars: Dict[str, str],
) -> Image

Use this method to create a new image with the specified environment variables layered on top of the current image. Cannot be used in conjunction with conda

with_local_v2()

def with_local_v2()

Use this method to create a new image with the local v2 builder This will override any existing builder

:return: Image

with_pip_packages()

def with_pip_packages(
    packages: str,
    index_url: Optional[str],
    extra_index_urls: Union[str, List[str], Tuple[str, ...], None],
    pre: bool,
    extra_args: Optional[str],
    secret_mounts: Optional[SecretRequest],
) -> Image

Use this method to create a new image with the specified pip packages layered on top of the current image Cannot be used in conjunction with conda

Example:

@flyte.task(image=(flyte.Image.from_debian_base().with_pip_packages("requests", "numpy")))
def my_task(x: int) -> int:
    import numpy as np
    return np.sum([x, 1])

To mount secrets during the build process to download private packages, you can use the secret_mounts. In the below example, “GITHUB_PAT” will be mounted as env var “GITHUB_PAT”, and “apt-secret” will be mounted at /etc/apt/apt-secret. Example:

private_package = "git+https://[email protected]/flyteorg/flytex.git@2e20a2acebfc3877d84af643fdd768edea41d533"
@flyte.task(
    image=(
        flyte.Image.from_debian_base()
        .with_pip_packages("private_package", secret_mounts=[Secret(key="GITHUB_PAT")])
        .with_apt_packages("git", secret_mounts=[Secret(key="apt-secret", mount="/etc/apt/apt-secret")])
)
def my_task(x: int) -> int:
    import numpy as np
    return np.sum([x, 1])

with_poetry_project()

def with_poetry_project(
    pyproject_file: str | Path,
    poetry_lock: Path | None,
    extra_args: Optional[str],
    secret_mounts: Optional[SecretRequest],
    project_install_mode: typing.Literal['dependencies_only', 'install_project'],
)

Use this method to create a new image with the specified pyproject.toml layered on top of the current image. Must have a corresponding pyproject.toml file in the same directory. Cannot be used in conjunction with conda.

By default, this method copies the entire project into the image, including files such as pyproject.toml, poetry.lock, and the src/ directory.

If you prefer not to install the current project, you can pass through extra_args --no-root. In this case, the image builder will only copy pyproject.toml and poetry.lock into the image.

with_requirements()

def with_requirements(
    file: str | Path,
    secret_mounts: Optional[SecretRequest],
) -> Image

Use this method to create a new image with the specified requirements file layered on top of the current image Cannot be used in conjunction with conda

with_source_file()

def with_source_file(
    src: Path,
    dst: str,
) -> Image

Use this method to create a new image with the specified local file layered on top of the current image. If dest is not specified, it will be copied to the working directory of the image

with_source_folder()

def with_source_folder(
    src: Path,
    dst: str,
    copy_contents_only: bool,
) -> Image

Use this method to create a new image with the specified local directory layered on top of the current image. If dest is not specified, it will be copied to the working directory of the image

with_uv_project()

def with_uv_project(
    pyproject_file: str | Path,
    uvlock: Path | None,
    index_url: Optional[str],
    extra_index_urls: Union[List[str], Tuple[str, ...], None],
    pre: bool,
    extra_args: Optional[str],
    secret_mounts: Optional[SecretRequest],
    project_install_mode: typing.Literal['dependencies_only', 'install_project'],
) -> Image

Use this method to create a new image with the specified uv.lock file layered on top of the current image Must have a corresponding pyproject.toml file in the same directory Cannot be used in conjunction with conda

By default, this method copies the pyproject.toml and uv.lock files into the image.

If project_install_mode is “install_project”, it will also copy directory where the pyproject.toml file is located into the image.

with_workdir()

def with_workdir(
    workdir: str,
) -> Image

Use this method to create a new image with the specified working directory This will override any existing working directory