Trait ImageExt 

pub trait ImageExt<I: Image> {
    // Required methods
    fn with_cmd(
        self,
        cmd: impl IntoIterator<Item = impl Into<String>>,
    ) -> ContainerRequest<I>;
    fn with_name(self, name: impl Into<String>) -> ContainerRequest<I>;
    fn with_tag(self, tag: impl Into<String>) -> ContainerRequest<I>;
    fn with_container_name(self, name: impl Into<String>) -> ContainerRequest<I>;
    fn with_platform(self, platform: impl Into<String>) -> ContainerRequest<I>;
    fn with_network(self, network: impl Into<String>) -> ContainerRequest<I>;
    fn with_label(
        self,
        key: impl Into<String>,
        value: impl Into<String>,
    ) -> ContainerRequest<I>;
    fn with_labels(
        self,
        labels: impl IntoIterator<Item = (impl Into<String>, impl Into<String>)>,
    ) -> ContainerRequest<I>;
    fn with_env_var(
        self,
        name: impl Into<String>,
        value: impl Into<String>,
    ) -> ContainerRequest<I>;
    fn with_host(
        self,
        key: impl Into<String>,
        value: impl Into<Host>,
    ) -> ContainerRequest<I>;
    fn with_hostname(self, hostname: impl Into<String>) -> ContainerRequest<I>;
    fn with_mount(self, mount: impl Into<Mount>) -> ContainerRequest<I>;
    fn with_copy_to(
        self,
        target: impl Into<CopyTargetOptions>,
        source: impl Into<CopyDataSource>,
    ) -> ContainerRequest<I>;
    fn with_mapped_port(
        self,
        host_port: u16,
        container_port: ContainerPort,
    ) -> ContainerRequest<I>;
    fn with_exposed_host_port(self, port: u16) -> ContainerRequest<I>;
    fn with_exposed_host_ports(
        self,
        ports: impl IntoIterator<Item = u16>,
    ) -> ContainerRequest<I>;
    fn with_ulimit(
        self,
        name: &str,
        soft: i64,
        hard: Option<i64>,
    ) -> ContainerRequest<I>;
    fn with_privileged(self, privileged: bool) -> ContainerRequest<I>;
    fn with_cap_add(self, capability: impl Into<String>) -> ContainerRequest<I>;
    fn with_cap_drop(self, capability: impl Into<String>) -> ContainerRequest<I>;
    fn with_cgroupns_mode(
        self,
        cgroupns_mode: CgroupnsMode,
    ) -> ContainerRequest<I>;
    fn with_userns_mode(self, userns_mode: &str) -> ContainerRequest<I>;
    fn with_shm_size(self, bytes: u64) -> ContainerRequest<I>;
    fn with_startup_timeout(self, timeout: Duration) -> ContainerRequest<I>;
    fn with_working_dir(
        self,
        working_dir: impl Into<String>,
    ) -> ContainerRequest<I>;
    fn with_log_consumer(
        self,
        log_consumer: impl LogConsumer + 'static,
    ) -> ContainerRequest<I>;
    fn with_host_config_modifier(
        self,
        modifier: impl Fn(&mut HostConfig) + Send + Sync + 'static,
    ) -> ContainerRequest<I>;
    fn with_reuse(self, reuse: ReuseDirective) -> ContainerRequest<I>;
    fn with_user(self, user: impl Into<String>) -> ContainerRequest<I>;
    fn with_readonly_rootfs(self, readonly_rootfs: bool) -> ContainerRequest<I>;
    fn with_security_opt(
        self,
        security_opt: impl Into<String>,
    ) -> ContainerRequest<I>;
    fn with_ready_conditions(
        self,
        ready_conditions: Vec<WaitFor>,
    ) -> ContainerRequest<I>;
    fn with_health_check(self, health_check: Healthcheck) -> ContainerRequest<I>;
    fn with_device_requests(
        self,
        device_requests: Vec<DeviceRequest>,
    ) -> ContainerRequest<I>;
}

Represents an extension for the Image trait. Allows to override image defaults and container configuration.

Required Methods

fn with_cmd( self, cmd: impl IntoIterator<Item = impl Into<String>>, ) -> ContainerRequest<I>

Returns a new ContainerRequest with the specified (overridden) CMD (Image::cmd).

Examples

use testcontainers::{GenericImage, ImageExt};

let image = GenericImage::new("image", "tag");
let cmd = ["arg1", "arg2"];
let overridden_cmd = image.clone().with_cmd(cmd);

assert!(overridden_cmd.cmd().eq(cmd));

let another_container_req = image.with_cmd(cmd);

assert!(another_container_req.cmd().eq(overridden_cmd.cmd()));

fn with_name(self, name: impl Into<String>) -> ContainerRequest<I>

Overrides the fully qualified image name (consists of {domain}/{owner}/{image}). Can be used to specify a custom registry or owner.

fn with_tag(self, tag: impl Into<String>) -> ContainerRequest<I>

Overrides the image tag.

There is no guarantee that the specified tag for an image would result in a running container. Users of this API are advised to use this at their own risk.

fn with_container_name(self, name: impl Into<String>) -> ContainerRequest<I>

Sets the container name.

fn with_platform(self, platform: impl Into<String>) -> ContainerRequest<I>

Sets the platform the container will be run on.

Platform in the format os[/arch[/variant]] used for image lookup.

Examples

use testcontainers::{GenericImage, ImageExt};

let image = GenericImage::new("image", "tag")
    .with_platform("linux/amd64");

fn with_network(self, network: impl Into<String>) -> ContainerRequest<I>

Sets the network the container will be connected to.

fn with_label( self, key: impl Into<String>, value: impl Into<String>, ) -> ContainerRequest<I>

Adds the specified label to the container.

Note: all keys in the org.testcontainers.* namespace should be regarded as reserved by testcontainers internally, and should not be expected or relied upon to be applied correctly if supplied as a value for key.

fn with_labels( self, labels: impl IntoIterator<Item = (impl Into<String>, impl Into<String>)>, ) -> ContainerRequest<I>

Adds the specified labels to the container.

Note: all keys in the org.testcontainers.* namespace should be regarded as reserved by testcontainers internally, and should not be expected or relied upon to be applied correctly if they are included in labels.

fn with_env_var( self, name: impl Into<String>, value: impl Into<String>, ) -> ContainerRequest<I>

Adds an environment variable to the container.

fn with_host( self, key: impl Into<String>, value: impl Into<Host>, ) -> ContainerRequest<I>

Adds a host to the container.

fn with_hostname(self, hostname: impl Into<String>) -> ContainerRequest<I>

Configures hostname for the container.

fn with_mount(self, mount: impl Into<Mount>) -> ContainerRequest<I>

Adds a mount to the container.

fn with_copy_to( self, target: impl Into<CopyTargetOptions>, source: impl Into<CopyDataSource>, ) -> ContainerRequest<I>

Copies data or a file/dir into the container.

The simplest form mirrors existing behavior:

use std::path::Path;
use testcontainers::{GenericImage, ImageExt};

let image = GenericImage::new("image", "tag");
image.with_copy_to("/app/config.toml", Path::new("./config.toml"));

By default the target mode is derived from the source file’s mode on Unix, and falls back to 0o644 on non-Unix platforms.

To override the mode (or add more target options), wrap the target with CopyTargetOptions:

use std::path::Path;
use testcontainers::{CopyTargetOptions, GenericImage, ImageExt};

let image = GenericImage::new("image", "tag");
image.with_copy_to(
    CopyTargetOptions::new("/app/config.toml").with_mode(0o600),
    Path::new("./config.toml"),
);

fn with_mapped_port( self, host_port: u16, container_port: ContainerPort, ) -> ContainerRequest<I>

Adds a port mapping to the container, mapping the host port to the container’s internal port.

Examples

use testcontainers::{GenericImage, ImageExt};
use testcontainers::core::IntoContainerPort;

let image = GenericImage::new("image", "tag").with_mapped_port(8080, 80.tcp());

fn with_exposed_host_port(self, port: u16) -> ContainerRequest<I>

Available on crate feature host-port-exposure only.

Declares a host port that should be reachable from inside the container.

fn with_exposed_host_ports( self, ports: impl IntoIterator<Item = u16>, ) -> ContainerRequest<I>

Available on crate feature host-port-exposure only.

Declares multiple host ports that should be reachable from inside the container.

fn with_ulimit( self, name: &str, soft: i64, hard: Option<i64>, ) -> ContainerRequest<I>

Adds a resource ulimit to the container.

Examples

use testcontainers::{GenericImage, ImageExt};

let image = GenericImage::new("image", "tag").with_ulimit("nofile", 65536, Some(65536));

fn with_privileged(self, privileged: bool) -> ContainerRequest<I>

Sets the container to run in privileged mode.

fn with_cap_add(self, capability: impl Into<String>) -> ContainerRequest<I>

Adds the capabilities to the container

fn with_cap_drop(self, capability: impl Into<String>) -> ContainerRequest<I>

Drops the capabilities from the container’s capabilities

fn with_cgroupns_mode(self, cgroupns_mode: CgroupnsMode) -> ContainerRequest<I>

cgroup namespace mode for the container. Possible values are:

• CgroupnsMode::Private: the container runs in its own private cgroup namespace
• CgroupnsMode::Host: use the host system’s cgroup namespace

If not specified, the daemon default is used, which can either be \"private\" or \"host\", depending on daemon version, kernel support and configuration.

fn with_userns_mode(self, userns_mode: &str) -> ContainerRequest<I>

Sets the usernamespace mode for the container when usernamespace remapping option is enabled.

fn with_shm_size(self, bytes: u64) -> ContainerRequest<I>

Sets the shared memory size in bytes

fn with_startup_timeout(self, timeout: Duration) -> ContainerRequest<I>

Sets the startup timeout for the container. The default is 60 seconds.

fn with_working_dir(self, working_dir: impl Into<String>) -> ContainerRequest<I>

Sets the working directory. The default is defined by the underlying image, which in turn may default to /.

fn with_log_consumer( self, log_consumer: impl LogConsumer + 'static, ) -> ContainerRequest<I>

Adds the log consumer to the container.

Allows to follow the container logs for the whole lifecycle of the container, starting from the creation.

fn with_host_config_modifier( self, modifier: impl Fn(&mut HostConfig) + Send + Sync + 'static, ) -> ContainerRequest<I>

Applies a custom modifier to the Docker HostConfig used for container creation.

The modifier runs after testcontainers finishes applying its defaults and settings. If called multiple times, the last modifier replaces the previous one.

fn with_reuse(self, reuse: ReuseDirective) -> ContainerRequest<I>

Available on crate feature reusable-containers only.

Flag the container as being exempt from the default testcontainers remove-on-drop lifecycle, indicating that the container should be kept running, and that executions with the same configuration reuse it instead of starting a “fresh” container instance.

NOTE: Reusable Containers is an experimental feature, and its behavior is therefore subject to change. Containers marked as reuse will not be stopped or cleaned up when their associated Container or ContainerAsync is dropped.

fn with_user(self, user: impl Into<String>) -> ContainerRequest<I>

Sets the user that commands are run as inside the container.

fn with_readonly_rootfs(self, readonly_rootfs: bool) -> ContainerRequest<I>

Sets the container’s root filesystem to be mounted as read-only

fn with_security_opt( self, security_opt: impl Into<String>, ) -> ContainerRequest<I>

Sets security options for the container

fn with_ready_conditions( self, ready_conditions: Vec<WaitFor>, ) -> ContainerRequest<I>

Overrides ready conditions.

There is no guarantee that the specified ready conditions for an image would result in a running container. Users of this API are advised to use this at their own risk.

fn with_health_check(self, health_check: Healthcheck) -> ContainerRequest<I>

Sets a custom health check for the container.

This will override any HEALTHCHECK instruction defined in the image. See Healthcheck for more details on how to build a health check.

Example

use testcontainers::{core::{Healthcheck, WaitFor}, GenericImage, ImageExt};
use std::time::Duration;

let image = GenericImage::new("mysql", "8.0")
    .with_wait_for(WaitFor::healthcheck())
    .with_health_check(
        Healthcheck::cmd(["mysqladmin", "ping", "-h", "localhost", "-u", "root", "-proot"])
            .with_interval(Duration::from_secs(2))
            .with_timeout(Duration::from_secs(1))
            .with_retries(5)
    );

fn with_device_requests( self, device_requests: Vec<DeviceRequest>, ) -> ContainerRequest<I>

Available on crate feature device-requests only.

Injects device requests into the container request.

This allows, for instance, exposing the underlying host’s GPU: https://docs.docker.com/compose/how-tos/gpu-support/#example-of-a-compose-file-for-running-a-service-with-access-to-1-gpu-device

This brings in 2 requirements:

• The host must have NVIDIA container toolkit installed.
• The image must have NVIDIA drivers installed.

Example

use testcontainers::{GenericImage, ImageExt as _, bollard::models::DeviceRequest};

let device_request = DeviceRequest {
    driver: Some(String::from("nvidia")),
    count: Some(-1), // expose all
    capabilities: Some(vec![vec![String::from("gpu")]]),
    device_ids: None,
    options: None,
};

let image = GenericImage::new("ubuntu", "24.04")
    .with_device_requests(vec![device_request]);

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl<RI: Into<ContainerRequest<I>>, I: Image> ImageExt<I> for RI

Implements the ImageExt trait for the every type that can be converted into a ContainerRequest.