Image

Container image specification built using a fluent, two-step pattern:

Create a base image with a from_* constructor
Customize with with_* methods (each returns a new Image)

Attributes

Attribute	Type	Description
base_image	`str` = null	The full URI of the starting container image used as the foundation for this specification.
dockerfile	`Path` = null	A file path to a custom Dockerfile used to build the image, which disables further layering.
registry	`str` = null	The container registry where the image will be pushed to or pulled from.
name	`str` = null	The identifier for the image used to construct the final URI and reference it in configuration.
platform	`Tuple[Architecture, ...]` = ("linux/amd64",)	The target CPU architectures for the build, defaulting to linux/amd64.
python_version	`Tuple[int, int]` = null	The specific version of Python to be installed or expected within the container environment.
extendable	`boolean` = false	Whether the image is extendable by other images, allowing additional layers to be added on top of it.

Methods

`validate()`

@classmethod
def validate()

Iterates through all defined image layers and triggers their individual validation logic.

`from_debian_base()`

@classmethod
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](image.md?sid=flyte__image_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.

Parameters

Name	Type	Description
python_version	`Optional[Tuple[int, int]]`	If not specified, will use the current Python version.
flyte_version	`Optional[str]`	Flyte version to use.
install_flyte	`bool`	If True, will install the flyte library in the image.
registry	`Optional[str]`	Registry to use for the image.
registry_secret	`Optional[str	Secret]`
name	`Optional[str]`	Name of the image if you want to override the default name.
platform	`Optional[Tuple[Architecture, ...]]`	Platform to use for the image, default is linux/amd64, use tuple for multiple values.

Returns

Type	Description
`[Image](image.md?sid=flyte__image_image)`	An Image instance based on the standard Debian distribution.

`from_base()`

@classmethod
def from_base(
    image_uri: str
) - > [Image](image.md?sid=flyte__image_image)

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

Parameters

Name	Type	Description
image_uri	`str`	The full URI of the image, in the format < registry >/< name >:< tag >.

Returns

Type	Description
`[Image](image.md?sid=flyte__image_image)`	An Image instance referencing the provided URI.

`from_ref_name()`

@classmethod
def from_ref_name(
    name: str
) - > [Image](image.md?sid=flyte__image_image)

Creates an Image reference using a logical name that maps to a pre-configured image URI.

Parameters

Name	Type	Description
name	`str`	The logical reference name defined in CLI or configuration.

Returns

Type	Description
`[Image](image.md?sid=flyte__image_image)`	An Image instance associated with the reference name.

`from_uv_script()`

@classmethod
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](image.md?sid=flyte__image_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.

Parameters

Name	Type	Description
script	`Path	str`
name	`str`	Name of the resulting image.
registry	`str	None`
registry_secret	`Optional[str	Secret]`
python_version	`Optional[Tuple[int, int]]`	Python version for the image; defaults to current version.
index_url	`Optional[str]`	Primary package index URL.
extra_index_urls	`Union[str, List[str], Tuple[str, ...], None]`	Additional package index URLs.
pre	`bool`	Whether to allow pre-release package versions.
extra_args	`Optional[str]`	Extra arguments to pass to the package installer.
platform	`Optional[Tuple[Architecture, ...]]`	Target architectures for the image.
secret_mounts	`Optional[SecretRequest]`	Secrets to mount during the build process.

Returns

Type	Description
`[Image](image.md?sid=flyte__image_image)`	An Image instance configured to run the specified uv script.

`clone()`

@classmethod
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],
    extendable: Optional[bool]
) - > [Image](image.md?sid=flyte__image_image)

Clone an existing image, optionally with a new name or registry.

Parameters

Name	Type	Description
registry	`Optional[str]`	Registry to use for the image.
registry_secret	`Optional[str	Secret]`
name	`Optional[str]`	Name of the image.
base_image	`Optional[str]`	Base image to use for the image.
python_version	`Optional[Tuple[int, int]]`	Python version for the image.
addl_layer	`Optional[Layer]`	Additional layer to add to the end of the image layers.
extendable	`Optional[bool]`	Whether the image can serve as a base for further layers.

Returns

Type	Description
`[Image](image.md?sid=flyte__image_image)`	A new Image instance with the updated properties and layers.

`from_dockerfile()`

@classmethod
def from_dockerfile(
    file: Union[Path, str],
    registry: str,
    name: str,
    platform: Union[Architecture, Tuple[Architecture, ...], None]
) - > [Image](image.md?sid=flyte__image_image)

Use this method to create a new image with the specified dockerfile. Note you cannot use additional layers after this.

Parameters

Name	Type	Description
file	`Union[Path, str]`	Path to the Dockerfile.
registry	`str`	Registry to use for the image.
name	`str`	Name of the image.
platform	`Union[Architecture, Tuple[Architecture, ...], None]`	Target architectures for the build.

Returns

Type	Description
`[Image](image.md?sid=flyte__image_image)`	An Image instance defined by the provided Dockerfile.

`uri()`

@classmethod
def uri() - > str

Returns the URI of the image in the format < registry >/< name >:< tag >.

Returns

Type	Description
`str`	The full resolvable URI of the image.

`with_workdir()`

@classmethod
def with_workdir(
    workdir: str
) - > [Image](image.md?sid=flyte__image_image)

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

Parameters

Name	Type	Description
workdir	`str`	The absolute path to set as the container's working directory.

Returns

Type	Description
`[Image](image.md?sid=flyte__image_image)`	A new Image instance with the updated working directory.

`with_requirements()`

@classmethod
def with_requirements(
    file: str | Path,
    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](image.md?sid=flyte__image_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.

Parameters

Name	Type	Description
file	`str	Path`
index_url	`Optional[str]`	Primary package index URL.
extra_index_urls	`Union[str, List[str], Tuple[str, ...], None]`	Additional package index URLs.
pre	`bool`	If True, install pre-release packages.
extra_args	`Optional[str]`	Extra arguments to pass to pip install.
secret_mounts	`Optional[SecretRequest]`	Secrets to mount during the build process.

Returns

Type	Description
`[Image](image.md?sid=flyte__image_image)`	A new Image instance with the requirements file layer added.

`with_pip_packages()`

@classmethod
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](image.md?sid=flyte__image_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.

Parameters

Name	Type	Description
*packages	`str`	List of pip packages to install, following pip install syntax.
index_url	`Optional[str]`	Primary package index URL.
extra_index_urls	`Union[str, List[str], Tuple[str, ...], None]`	Additional package index URLs.
pre	`bool`	Whether to allow pre-release versions.
extra_args	`Optional[str]`	Extra arguments to pass to pip install.
secret_mounts	`Optional[SecretRequest]`	Secrets to mount during the build process.

Returns

Type	Description
`[Image](image.md?sid=flyte__image_image)`	A new Image instance with the specified pip packages installed.

`with_env_vars()`

@classmethod
def with_env_vars(
    env_vars: Dict[str, str]
) - > [Image](image.md?sid=flyte__image_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.

Parameters

Name	Type	Description
env_vars	`Dict[str, str]`	Dictionary of environment variable keys and values.

Returns

Type	Description
`[Image](image.md?sid=flyte__image_image)`	A new Image instance with the environment variables set.

`with_source_folder()`

@classmethod
def with_source_folder(
    src: Path,
    dst: str,
    copy_contents_only: bool
) - > [Image](image.md?sid=flyte__image_image)

Use this method to create a new image with the specified local directory layered on top of the current image.

Parameters

Name	Type	Description
src	`Path`	Root folder of the source code from the build context to be copied.
dst	`str`	Destination folder path within the image.
copy_contents_only	`bool`	If True, copies the contents of the source folder instead of the folder itself.

Returns

Type	Description
`[Image](image.md?sid=flyte__image_image)`	A new Image instance containing the copied folder.

`with_source_file()`

@classmethod
def with_source_file(
    src: typing.Union[Path, typing.List[Path]],
    dst: str
) - > [Image](image.md?sid=flyte__image_image)

Use this method to create a new image with the specified local file(s) layered on top of the current image.

Parameters

Name	Type	Description
src	`typing.Union[Path, typing.List[Path]]`	File or list of files from the build context to be copied.
dst	`str`	Destination folder path within the image.

Returns

Type	Description
`[Image](image.md?sid=flyte__image_image)`	A new Image instance containing the copied file(s).

`with_code_bundle()`

@classmethod
def with_code_bundle(
    copy_style: Literal["loaded_modules", "all"],
    dst: str
) - > [Image](image.md?sid=flyte__image_image)

Configure this image to automatically copy source code from root_dir when the runner's copy_style is "none".

Parameters

Name	Type	Description
copy_style	`Literal["loaded_modules", "all"]`	Which files to copy: only imported modules or all files from root_dir.
dst	`str`	Destination directory in the container.

Returns

Type	Description
`[Image](image.md?sid=flyte__image_image)`	A new Image instance with code bundling configured.

`with_dockerignore()`

@classmethod
def with_dockerignore(
    path: Path
) - > [Image](image.md?sid=flyte__image_image)

Adds a .dockerignore file to the image build context to exclude specific files and directories.

Parameters

Name	Type	Description
path	`Path`	Path to the .dockerignore file.

Returns

Type	Description
`[Image](image.md?sid=flyte__image_image)`	A new Image instance with the dockerignore layer added.

`with_uv_project()`

@classmethod
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](image.md?sid=flyte__image_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.

Parameters

Name	Type	Description
pyproject_file	`str	Path`
uvlock	`Path	None`
index_url	`Optional[str]`	Primary package index URL.
extra_index_urls	`Union[List[str], Tuple[str, ...], None]`	Additional package index URLs.
pre	`bool`	Whether to allow pre-release versions.
extra_args	`Optional[str]`	Extra arguments to pass to pip install.
secret_mounts	`Optional[SecretRequest]`	Secrets to mount during the build process.
project_install_mode	`typing.Literal["dependencies_only", "install_project"]`	Whether to install only dependencies or the project itself as a package.

Returns

Type	Description
`[Image](image.md?sid=flyte__image_image)`	A new Image instance with the uv project dependencies installed.

`with_poetry_project()`

@classmethod
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"]
) - > [Image](image.md?sid=flyte__image_image)

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.

Parameters

Name	Type	Description
pyproject_file	`str	Path`
poetry_lock	`Path	None`
extra_args	`Optional[str]`	Extra arguments to pass to the package installer.
secret_mounts	`Optional[SecretRequest]`	Secrets to mount during the build process.
project_install_mode	`typing.Literal["dependencies_only", "install_project"]`	Whether to install only dependencies or the project itself as a package.

Returns

Type	Description
`[Image](image.md?sid=flyte__image_image)`	A new Image instance with the Poetry project dependencies installed.

`with_apt_packages()`

@classmethod
def with_apt_packages(
    *packages: str,
    secret_mounts: Optional[SecretRequest]
) - > [Image](image.md?sid=flyte__image_image)

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

Parameters

Name	Type	Description
*packages	`str`	List of apt packages to install.
secret_mounts	`Optional[SecretRequest]`	Secrets to mount during the build process.

Returns

Type	Description
`[Image](image.md?sid=flyte__image_image)`	A new Image instance with the system packages installed.

`with_commands()`

@classmethod
def with_commands(
    commands: List[str],
    secret_mounts: Optional[SecretRequest]
) - > [Image](image.md?sid=flyte__image_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.

Parameters

Name	Type	Description
commands	`List[str]`	List of shell commands to run.
secret_mounts	`Optional[SecretRequest]`	Secrets to mount during the build process.

Returns

Type	Description
`[Image](image.md?sid=flyte__image_image)`	A new Image instance that will execute the specified commands during build.

`with_local_v2()`

@classmethod
def with_local_v2() - > [Image](image.md?sid=flyte__image_image)

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

Returns

Type	Description
`[Image](image.md?sid=flyte__image_image)`	A new Image instance configured for local v2 execution.

`with_local_v2_plugins()`

@classmethod
def with_local_v2_plugins(
    plugins: str | list[str]| None
) - > [Image](image.md?sid=flyte__image_image)

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

Parameters

Name	Type	Description
plugins	`str	list[str]

Returns

Type	Description
`[Image](image.md?sid=flyte__image_image)`	A new Image instance with the specified local plugins installed.

Attributes​

Methods​

validate()​

from_debian_base()​

Parameters​

Returns​

from_base()​

Parameters​

Returns​

from_ref_name()​

Parameters​

Returns​

from_uv_script()​

Parameters​

Returns​

clone()​

Parameters​

Returns​

from_dockerfile()​

Parameters​

Returns​

uri()​

Returns​

with_workdir()​

Parameters​

Returns​

with_requirements()​

Parameters​

Returns​

with_pip_packages()​

Parameters​

Returns​

with_env_vars()​

Parameters​

Returns​

with_source_folder()​

Parameters​

Returns​

with_source_file()​

Parameters​

Returns​

with_code_bundle()​

Parameters​

Returns​

with_dockerignore()​

Parameters​

Returns​

with_uv_project()​

Parameters​

Returns​

with_poetry_project()​

Parameters​

Returns​

with_apt_packages()​

Parameters​

Returns​

with_commands()​

Parameters​

Returns​

with_local_v2()​

Returns​

with_local_v2_plugins()​

Parameters​

Returns​

Attributes

Methods

`validate()`

`from_debian_base()`

Parameters

Returns

`from_base()`

Parameters

Returns

`from_ref_name()`

Parameters

Returns

`from_uv_script()`

Parameters

Returns

`clone()`

Parameters

Returns

`from_dockerfile()`

Parameters

Returns

`uri()`

Returns

`with_workdir()`

Parameters

Returns

`with_requirements()`

Parameters

Returns

`with_pip_packages()`

Parameters

Returns

`with_env_vars()`

Parameters

Returns

`with_source_folder()`

Parameters

Returns

`with_source_file()`

Parameters

Returns

`with_code_bundle()`

Parameters

Returns

`with_dockerignore()`

Parameters

Returns

`with_uv_project()`

Parameters

Returns

`with_poetry_project()`

Parameters

Returns

`with_apt_packages()`

Parameters

Returns

`with_commands()`

Parameters

Returns

`with_local_v2()`

Returns

`with_local_v2_plugins()`

Parameters

Returns