Image

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

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

Attributes

Attribute	Type	Description
base_image	Optional[str] = null	The base image URI from which this image is derived, if not built from a Dockerfile.
dockerfile	Optional[Path] = null	The path to a Dockerfile used to build this image, if applicable.
registry	Optional[str] = null	The container registry where this image will be stored or pulled from.
name	Optional[str] = null	The name of the image within the registry.
platform	Tuple[Architecture, ...] = ("linux/amd64",)	The target platform(s) for the image, such as 'linux/amd64' or 'linux/arm64'.
python_version	Tuple[int, int] = _detect_python_version	The Python version used in the image, represented as a tuple (major, minor).
extendable	bool = false	A boolean indicating whether additional layers can be added to this image after its creation.

---

Methods

---

validate()

@classmethod
def validate() - > null

Validates all layers associated with the image. This ensures that each layer's configuration is correct before the image is built or used.

Returns

Type	Description
null	This method does not return any value.

---

from_debian_base()

@classmethod
def from_debian_base(
    python_version: Optional[Tuple[int, int]] = None,
    flyte_version: Optional[str] = None,
    install_flyte: bool = True,
    registry: Optional[str] = None,
    registry_secret: Optional[str | Secret] = None,
    name: Optional[str] = None,
    platform: Optional[Tuple[Architecture, ...]] = None
) - > [Image](image.md?sid=flyte__image_image)

Creates a new Image instance using a default Debian-based image with a specified Python version. This is a convenient constructor for starting with a standard, multi-architecture base image.

Parameters

Name	Type	Description
python_version	Optional[Tuple[int, int]] = None	The major and minor Python version (e.g., (3, 10)) to use. If None, the current Python version will be detected and used.
flyte_version	Optional[str] = None	The Flyte version to include in the image. If None, the current SDK version is used.
install_flyte	bool = True	A boolean indicating whether to install the Flyte library in the image.
registry	Optional[str] = None	The container registry where the image will be stored. If None, a default registry is used.
registry_secret	`Optional[str	Secret]` = None
name	Optional[str] = None	A custom name for the image. If None, a default name is generated.
platform	Optional[Tuple[Architecture, ...]] = None	The target platform(s) for the image, such as 'linux/amd64' or 'linux/arm64'. If None, defaults to multi-arch 'linux/amd64', 'linux/arm64'.

Returns

Type	Description
[Image](image.md?sid=flyte__image_image)	A new Image object configured with the specified Debian base.

---

from_base()

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

Creates a new Image instance from a pre-built base image specified by its full URI. This method is used when you want to start with an existing image that is already available in a registry.

Parameters

Name	Type	Description
image_uri	str	The full URI of the base image, including registry, name, and tag (e.g., 'myregistry/myimage:mytag').

Returns

Type	Description
[Image](image.md?sid=flyte__image_image)	A new Image object configured with the specified base image URI.

---

from_ref_name()

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

Creates an Image instance by referencing a pre-built image using its name. This allows you to refer to images defined elsewhere (e.g., in CLI or configuration) and potentially add further layers.

Parameters

Name	Type	Description
name	str = _DEFAULT_IMAGE_REF_NAME	The reference name of the pre-built image.

Returns

Type	Description
[Image](image.md?sid=flyte__image_image)	A new Image object referencing the specified image name.

---

from_uv_script()

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

Creates a new Image instance by parsing a uv-compatible script to determine Python version and dependencies. This method is useful for building images where dependencies are declared directly within a script's header.

Parameters

Name	Type	Description
script	`Path	str`
name	str	The name of the image to be created.
registry	`str	None` = None
registry_secret	`Optional[str	Secret]` = None
python_version	Optional[Tuple[int, int]] = None	The major and minor Python version (e.g., (3, 10)) to use. If None, the Python version specified in the script's header or the current Python version will be used.
index_url	Optional[str] = None	The base URL of the Python package index to use for dependency resolution.
extra_index_urls	Union[str, List[str], Tuple[str, ...], None] = None	Additional URLs of Python package indexes to use for dependency resolution.
pre	bool = False	A boolean indicating whether to allow pre-release versions of packages during installation.
extra_args	Optional[str] = None	Additional arguments to pass directly to the uv installation command.
platform	Optional[Tuple[Architecture, ...]] = None	The target platform(s) for the image, such as 'linux/amd64' or 'linux/arm64'. If None, defaults to 'linux/amd64'.
secret_mounts	Optional[SecretRequest] = None	A list of secret requests to mount during the image build process, useful for accessing private package indexes.

Returns

Type	Description
[Image](image.md?sid=flyte__image_image)	A new Image object configured based on the uv script.

---

clone()

@classmethod
def clone(
    registry: Optional[str] = None,
    registry_secret: Optional[str | Secret] = None,
    name: Optional[str] = None,
    base_image: Optional[str] = None,
    python_version: Optional[Tuple[int, int]] = None,
    addl_layer: Optional[Layer] = None,
    extendable: Optional[bool] = None
) - > [Image](image.md?sid=flyte__image_image)

Creates a new Image instance that is a copy of the current image, allowing for modifications to its base properties or the addition of new layers. This method is essential for the fluent API pattern, where each with_* method returns a new, modified Image.

Parameters

Name	Type	Description
registry	Optional[str] = None	The container registry where the cloned image will be stored. If None, the original image's registry is retained.
registry_secret	`Optional[str	Secret]` = None
name	Optional[str] = None	A custom name for the cloned image. If None, the original image's name is retained.
base_image	Optional[str] = None	A new base image URI to use for the cloned image. If None, the original image's base image is retained.
python_version	Optional[Tuple[int, int]] = None	The major and minor Python version (e.g., (3, 10)) for the cloned image. If None, the original image's Python version is retained.
addl_layer	Optional[Layer] = None	An additional layer to append to the cloned image's existing layers. This allows for incremental modifications.
extendable	Optional[bool] = None	A boolean indicating whether the cloned image can be further extended with additional layers. If None, the original image's extendable property is retained.

Returns

Type	Description
[Image](image.md?sid=flyte__image_image)	A new Image object, which is a deep copy of the original with specified modifications.

---

from_dockerfile()

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

Creates a new Image instance from a custom Dockerfile. This method provides maximum flexibility for image definition but prevents further layering using with_* methods, as the system does not parse the Dockerfile's contents.

Parameters

Name	Type	Description
file	Union[Path, str]	The file path to the Dockerfile. It is recommended to use an absolute Path object.
registry	str	The container registry where the image will be stored.
name	str	The name of the image to be created.
platform	Union[Architecture, Tuple[Architecture, ...], None] = None	The target platform(s) for the image, such as 'linux/amd64' or 'linux/arm64'. If None, defaults to 'linux/amd64'.

Returns

Type	Description
[Image](image.md?sid=flyte__image_image)	A new Image object configured from the specified Dockerfile.

---

uri()

@classmethod
def uri() - > str

Constructs and returns the full URI of the image, combining the registry, name, and final tag. This URI uniquely identifies the image in a container registry.

Returns

Type	Description
str	A string representing the full URI of the image (e.g., 'myregistry/myimage:mytag').

---

with_workdir()

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

Creates a new Image instance with a specified working directory. This method allows you to define the default directory where commands will be executed inside the container.

Parameters

Name	Type	Description
workdir	str	The working directory path to set inside the image.

Returns

Type	Description
[Image](image.md?sid=flyte__image_image)	A new Image object with the specified working directory configured.

---

with_requirements()

@classmethod
def with_requirements(
    file: str | Path,
    index_url: Optional[str] = None,
    extra_index_urls: Union[str, List[str], Tuple[str, ...], None] = None,
    pre: bool = False,
    extra_args: Optional[str] = None,
    secret_mounts: Optional[SecretRequest] = None
) - > [Image](image.md?sid=flyte__image_image)

Creates a new Image instance that includes Python packages specified in a requirements.txt file. This method is used to install dependencies from a standard Python requirements file.

Parameters

Name	Type	Description
file	`str	Path`
index_url	Optional[str] = None	The base URL of the Python package index to use for dependency resolution.
extra_index_urls	Union[str, List[str], Tuple[str, ...], None] = None	Additional URLs of Python package indexes to use for dependency resolution.
pre	bool = False	A boolean indicating whether to allow pre-release versions of packages during installation.
extra_args	Optional[str] = None	Additional arguments to pass directly to the pip install command.
secret_mounts	Optional[SecretRequest] = None	A list of secret requests to mount during the image build process, useful for accessing private package indexes.

Returns

Type	Description
[Image](image.md?sid=flyte__image_image)	A new Image object with the specified requirements installed.

---

with_pip_packages()

@classmethod
def with_pip_packages(
    *packages: str,
    index_url: Optional[str] = None,
    extra_index_urls: Union[str, List[str], Tuple[str, ...], None] = None,
    pre: bool = False,
    extra_args: Optional[str] = None,
    secret_mounts: Optional[SecretRequest] = None
) - > [Image](image.md?sid=flyte__image_image)

Creates a new Image instance with specified Python packages installed using pip. This method allows for direct installation of individual Python packages and their versions.

Parameters

Name	Type	Description
*packages	str	A variable number of strings, each representing a pip package specification (e.g., 'requests', 'numpy==1.20.0').
index_url	Optional[str] = None	The base URL of the Python package index to use for dependency resolution.
extra_index_urls	Union[str, List[str], Tuple[str, ...], None] = None	Additional URLs of Python package indexes to use for dependency resolution.
pre	bool = False	A boolean indicating whether to allow pre-release versions of packages during installation.
extra_args	Optional[str] = None	Additional arguments to pass directly to the pip install command.
secret_mounts	Optional[SecretRequest] = None	A list of secret requests to mount during the image build process, useful for accessing private package indexes.

Returns

Type	Description
[Image](image.md?sid=flyte__image_image)	A new Image object 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)

Creates a new Image instance with specified environment variables set. This method allows you to configure environment-specific settings that will be available inside the container.

Parameters

Name	Type	Description
env_vars	Dict[str, str]	A dictionary where keys are environment variable names and values are their corresponding string values.

Returns

Type	Description
[Image](image.md?sid=flyte__image_image)	A new Image object with the specified environment variables configured.

---

with_source_folder()

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

Creates a new Image instance that includes a local directory copied into the image. This method is used to add source code or other assets from your local filesystem to the container.

Parameters

Name	Type	Description
src	Path	The path to the local source folder to be copied. This path is relative to the build context.
dst	str = .	The destination path inside the image where the source folder will be copied. Defaults to the working directory.
copy_contents_only	bool = False	A boolean indicating whether to copy only the contents of the source folder (True) or the folder itself (False) into the destination.

Returns

Type	Description
[Image](image.md?sid=flyte__image_image)	A new Image object with the specified source folder copied into it.

---

with_source_file()

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

Creates a new Image instance that includes one or more local files copied into the image. This method is used to add specific files from your local filesystem to the container.

Parameters

Name	Type	Description
src	typing.Union[Path, typing.List[Path]]	The path to a single local file or a list of paths to local files to be copied. These paths are relative to the build context.
dst	str = .	The destination path inside the image where the source file(s) will be copied. Defaults to the working directory.

Returns

Type	Description
[Image](image.md?sid=flyte__image_image)	A new Image object with the specified source file(s) copied into it.

---

with_code_bundle()

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

Configures the image to automatically copy source code from the root directory based on a specified copy style. This method helps ensure that necessary application code is present in the container for execution.

Parameters

Name	Type	Description
copy_style	Literal["loaded_modules", "all"] = loaded_modules	The strategy for copying code: 'loaded_modules' copies only imported Python modules, while 'all' copies all files from the root directory.
dst	str = .	The destination directory inside the container where the code bundle will be copied. Defaults to the working directory.

Returns

Type	Description
[Image](image.md?sid=flyte__image_image)	A new Image object configured to include the specified code bundle.

---

with_dockerignore()

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

Creates a new Image instance that incorporates a .dockerignore file. This method allows you to specify patterns for files and directories that should be excluded from the build context when building the Docker image.

Parameters

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

Returns

Type	Description
[Image](image.md?sid=flyte__image_image)	A new Image object configured with the specified .dockerignore file.

---

with_uv_project()

@classmethod
def with_uv_project(
    pyproject_file: str | Path,
    uvlock: Path | None = None,
    index_url: Optional[str] = None,
    extra_index_urls: Union[List[str], Tuple[str, ...], None] = None,
    pre: bool = False,
    extra_args: Optional[str] = None,
    secret_mounts: Optional[SecretRequest] = None,
    project_install_mode: typing.Literal["dependencies_only", "install_project"] = dependencies_only
) - > [Image](image.md?sid=flyte__image_image)

Creates a new Image instance that installs dependencies from a uv project, typically defined by pyproject.toml and uv.lock files. This method is used for projects managed with uv to ensure consistent dependency installation.

Parameters

Name	Type	Description
pyproject_file	`str	Path`
uvlock	`Path	None` = None
index_url	Optional[str] = None	The base URL of the Python package index to use for dependency resolution.
extra_index_urls	Union[List[str], Tuple[str, ...], None] = None	Additional URLs of Python package indexes to use for dependency resolution.
pre	bool = False	A boolean indicating whether to allow pre-release versions of packages during installation.
extra_args	Optional[str] = None	Additional arguments to pass directly to the uv installation command.
secret_mounts	Optional[SecretRequest] = None	A list of secret requests to mount during the image build process, useful for accessing private package indexes.
project_install_mode	typing.Literal["dependencies_only", "install_project"] = dependencies_only	Determines whether to install only the project's dependencies ('dependencies_only') or to also install the project itself as a package ('install_project').

Returns

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

---

with_poetry_project()

@classmethod
def with_poetry_project(
    pyproject_file: str | Path,
    poetry_lock: Path | None = None,
    extra_args: Optional[str] = None,
    secret_mounts: Optional[SecretRequest] = None,
    project_install_mode: typing.Literal["dependencies_only", "install_project"] = dependencies_only
) - > null

Creates a new Image instance that installs dependencies from a Poetry project, typically defined by pyproject.toml and poetry.lock files. This method is used for projects managed with Poetry to ensure consistent dependency installation.

Parameters

Name	Type	Description
pyproject_file	`str	Path`
poetry_lock	`Path	None` = None
extra_args	Optional[str] = None	Additional arguments to pass directly to the Poetry installation command (e.g., --no-root to install only dependencies).
secret_mounts	Optional[SecretRequest] = None	A list of secret requests to mount during the image build process, useful for accessing private package indexes.
project_install_mode	typing.Literal["dependencies_only", "install_project"] = dependencies_only	Determines whether to install only the project's dependencies ('dependencies_only') or to also install the project itself as a package ('install_project').

Returns

Type	Description
null	This method does not return any value.

---

with_apt_packages()

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

Creates a new Image instance that installs specified APT packages. This method is used to add system-level dependencies that are available through the APT package manager on Debian-based images.

Parameters

Name	Type	Description
*packages	str	A variable number of strings, each representing an APT package name (e.g., 'curl', 'git').
secret_mounts	Optional[SecretRequest] = None	A list of secret requests to mount during the image build process, useful for accessing private APT repositories.

Returns

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

---

with_commands()

@classmethod
def with_commands(
    commands: List[str],
    secret_mounts: Optional[SecretRequest] = None
) - > [Image](image.md?sid=flyte__image_image)

Creates a new Image instance that executes a list of shell commands during the image build process. This method provides a way to run arbitrary shell commands for custom setup or configuration within the container.

Parameters

Name	Type	Description
commands	List[str]	A list of strings, where each string is a shell command to be executed. Do not include 'RUN' in the commands.
secret_mounts	Optional[SecretRequest] = None	A list of secret requests to mount during the image build process, useful for commands requiring sensitive information.

Returns

Type	Description
[Image](image.md?sid=flyte__image_image)	A new Image object with the specified commands configured to run during build.

---

with_local_v2()

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

Configures the image to use the local v2 builder, typically for local development and testing. This method ensures that the image is set up to work with the local Flyte v2 environment.

Returns

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

---

with_local_v2_plugins()

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

Configures the image to include specified Flyte v2 plugins for local development. This method allows you to add specific plugin functionalities to your local v2 environment.

Parameters

Name	Type	Description
plugins	`str	list[str]

Returns

Type	Description
[Image](image.md?sid=flyte__image_image)	A new Image object configured with the specified local v2 plugins.

---