CHANGELOG.md

Changelog

All notable changes to this project will be documented in this file.

[0.27.3] - 2026-04-15

Details

Bug Fixes

• Pass Docker Hub credentials for images without a registry prefix (#935)

Miscellaneous Tasks

• Update docker-compose-types requirement from 0.22 to 0.23 (#931)
• Update ferroid requirement from 0.8.7 to 2.0.0 (#929)
• Update russh requirement from 0.56.0 to 0.60.0 (#933)
• Update signal-hook requirement from 0.3 to 0.4 (#934)
• Update temp-dir requirement from 0.1 to 0.2 (#921)

[0.27.2] - 2026-03-23

Details

Miscellaneous Tasks

• Update astral-tokio-tar requirement from 0.5.6 to 0.6.0 (#927)

[0.27.1] - 2026-02-22

Details

Bug Fixes

• Pass env vars via Docker exec API instead of prepending to command (#920)

Features

• Allow people to disable the default wait behavior (#922)

[0.27.0] - 2026-02-06

Details

Features

• Add User-Agent header 'tc-rust/' to Docker API requests (#897)
• Open stdin option for container request (#904)

Miscellaneous Tasks

• Update russh requirement from 0.55.0 to 0.56.0 (#902)
• Update reqwest requirement from 0.12.5 to 0.13.1 (#905)

[0.26.4] - 2026-02-05

Details

Features

• Add User-Agent header 'tc-rust/' to Docker API requests (#897)

Miscellaneous Tasks

• Update russh requirement from 0.55.0 to 0.56.0 (#902)
• Update reqwest requirement from 0.12.5 to 0.13.1 (#905)

[0.26.3] - 2025-12-24

Details

Features

• Support for reusable containers that have been stopped (#896)
• Support auto-detection of docker-compose client (#898)
• Allow customizations of host-config (#899)

[0.26.2] - 2025-12-19

Details

Features

• Allow overriding project name (#894)

[0.26.1] - 2025-12-19

Details

Bug Fixes

• Reuse container requires name (#887)
• Respect TESTCONTAINERS_COMMAND (#891)

Miscellaneous Tasks

• Update russh requirement from 0.54.4 to 0.55.0 (#888)

[0.26.0] - 2025-12-01

Details

Bug Fixes

• Make port_bindings consistent with docker cli when publish_all_ports = true (#885)

Features

• Support build options - no_cache, skip_if_exists and buildargs (#856)
• Support docker-compose (#864)
• Add target options with custom mode (#878)
• Support copying from containers (#871)

Miscellaneous Tasks

• Use bollard 0.19.4 (#870)
• Update etcetera requirement from 0.10.0 to 0.11.0 (#869)

Performance

• Replace ulid with ferroid's ULID for better performance (#829)
• Update ferroid for better performance during encode/decode (#879)

[0.25.2] - 2025-10-27

Details

Features

• Platform config passing through ImageExt trait (#838)

Miscellaneous Tasks

• Remove usage of reqwest hickory dns feature (#860)
• Drop weak dependencies due to cargo bug (#862)

[0.25.1] - 2025-10-27

Details

Bug Fixes

• Replace tokio-tar with astral-tokio-tar (#852)

Documentation

• Rustdoc for builder API (#820)

Features

• Use DOCKER_DEFAULT_PLATFORM env var to specify platform (#800)
• Fallback to platform linux/amd64 when image pull fails (#837)
• Add support for devices request (#832)
• Add configurable tmpfs mount sizes (#853)
• Support http_wait functionallity without tls dependencies (#850)
• Add container hostname support (#848)
• Expose host ports between host and containers via ssh sidecar (#846)

Miscellaneous Tasks

• Update bollard-stubs requirement from =1.48.3-rc.28.0.4 to =1.49.0-rc.28.3.3 (#828)

Refactor

• Remove bollard_stubs dependency as bollard re-exports it (#844)

Testing

• Avoid flakiness in platform test
• Switch to testcontainers/helloworld and reduce some flakiness (#855)

[0.25.0] - 2025-07-27

Details

Bug Fixes

• Make tls features optional (#806)
• Add Send trait to stderr & stdout of ExecResult (#809)
• Added new parse rule for correctly parsing ports without protocol specifier (#812)

Features

• Allow ready conditions customization via ImageExt (#794)
• Allow to wait for log line on either stdout or stderr (#795)
• Add Container*::exit_code (#791)
• Add Container*::is_running (#790)
• Add custom health check support for containers (#816)
• Introduce container builder api (#801)

Miscellaneous Tasks

• [❗] Update bollard to 1.19.1 (#817)

Refactor

• Testimages and tests to use builder API (#804)

[0.24.0] - 2025-05-04

Details

Features

• Support waiting for commands exit regardless of exit code (#771)
• Add user configuration for container commands (#784)
• Add option to stop containers with a timeout (#779)
• Support pause and unpause container (#785)
• Allow security_opt and readonly_rootfs to be configured (#787)

Miscellaneous Tasks

• Update etcetera requirement from 0.8.0 to 0.9.0 (#773)
• Update etcetera requirement from 0.9.0 to 0.10.0 (#775)

[0.23.3] - 2025-02-19

Details

Bug Fixes

• Proper handling of possible stdin in logs stream (#769)

Features

• Re-export bollard

[0.23.2] - 2025-02-06

Details

Documentation

• Add examples of ImageExt usage and cover GenericImage (#747)

Features

• Add cap_add and cap_drop support (#726)
• Add support for user-configured labels (#756)
• Reusable containers (#757)
• Add image hook to run commands before ready (#766)

Miscellaneous Tasks

• Update thiserror requirement from 1.0.60 to 2.0.3 (#754)
• Bump the bollard dep to latest (#759)

Testing

• Deflake the test start_containers_in_parallel (#748)

[0.23.1] - 2024-09-26

Details

Features

• Expose configured bollard client (#740)

[0.23.0] - 2024-09-25

Details

Bug Fixes

• Expose public copy types (#734)
• Typo in an error variant (#738)

Features

• Support copy files to container (#730)
• Support copying directories to container (#735)

Miscellaneous Tasks

• Copy-to-container interface improvements (#732)

Refactor

• Replace dirs crate with etcetera (#736)

[0.22.0] - 2024-08-30

Details

Bug Fixes

• [❗] Docker socket detection on unix (#721)

Features

• Add working_dir to ContainerRequest,ImageExt (#724)

Miscellaneous Tasks

• Added #![forbid(unsafe_code)] to the library (#722)

[0.21.1] - 2024-08-05

Details

Features

• Allow configuring resource ulimits (#714)

[0.21.0] - 2024-07-30

Details

Bug Fixes

• Don't assume docker host is a url (#709)

Miscellaneous Tasks

• Bump the bollard group across 1 directory with 2 updates (#710)

Refactor

• [❗] Put reqwest behind http_wait feature (#705)

[0.20.1] - 2024-07-18

Details

Bug Fixes

• Trim newline char from the mirrored messages (#699)

Features

• Support optional prefix for LoggingConsumer (#698)

[0.20.0] - 2024-07-07

Details

Bug Fixes

• [❗] Drop Clone impl for ContainerRequest (#680)
• Exclude image pulling time from startup timeout (#687)
• Waiting for mutiple messages from the same log frame (#688)
• Pass correct log-source for stderr wait strategy (#692)

Features

• Introduce log consumers (#681)
• Introduce LoggingConsumer based on log crate (#682)
• [❗] Enhance LogWaitStrategy to wait for message appearance multiple times (#683)
• [❗] Introduce ExitWaitStrategy (#684)

Miscellaneous Tasks

• Get rid of outdated variables naming (#679)
• Relax log level for log producer error (#685)
• Re-configure blocking runtime (#690)

Performance

• Avoid spawning log producer without consumers (#689)

Refactor

• Internal log processing structures (#678)

Styling

• Apply clippy suggestion (#693)

[0.19.0] - 2024-06-27

Details

Bug Fixes

• [❗] Use rustls-tls as default for reqwest (#672)

Documentation

• Update examples of GenericImage::with_exposed_port (#670)

Features

• Add ability to convert ContainerPort to u16 (#664)

Miscellaneous Tasks

• Make ports module public (#665)

Performance

• Use separate dropper thread for current_thread flavor (#666)

Refactor

• Use multi-threaded runtime for blocking feature (#667)

[0.18.0] - 2024-06-15

Details

Bug Fixes

• [❗] Make DOCKER_CONFIG usage consistent with Docker CLI (#654)

Features

• [❗] Support UDP and SCTP port mappings (#655)
• Impl From<u16> for ContainerPort with TCP default (#658)
• Support HTTP wait strategy (#659)
• Allow passing u16 to Ports

Miscellaneous Tasks

• Use nightly rustfmt (#657)

Refactor

• [❗] Get rid of associated type ImageArgs and rename to cmd (#649)
• Avoid unnecessary owned structs and boxing (#651)
• [❗] Add ImageExt trait to avoid explicit conversion to RunnableImage (#652)
• [❗] Rename RunnableImage to ContainerRequest (#653)
• [❗] Exposed and mapped ports api (#656)
• Preliminary refactoring of wait strategies (#661)

[0.17.0] - 2024-05-26

Details

Bug Fixes

• Collect bridge IP address correctly (#626)
• Replace missed panics with Result (#638)

Features

• Impl Error for WaitError (#629)
• [❗] Extend exec interface to return logs and exec code (#631)
• Ability to access container logs (#633)
• [❗] Switch to fallible API (#636)
• Make container and exec logs Sendable (#637)
• Map container not found error to eof for container log streams (#639)
• Expose follow flag for stdout and stderr (#640)
• Add ability to read container logs into Vec (#641)
• [❗] Add container startup timeout with default of 1 minute (#643)

Miscellaneous Tasks

• Fix clippy warning without features enabled (#632)

Refactor

• [❗] Drop re-export of CgroupnsMode accessible through core (#630)
• [❗] Drop previously deprecated get_host_ip_address (#628)
• [❗] Return PortNotExposed error from ContainerState::host_port_* (#644)

[0.16.7] - 2024-05-01

Details

Bug Fixes

• get_host for unix and npipe docker hosts (#621)

Features

• Extend WaitFor for ExecCommand (#622)

[0.16.6] - 2024-04-30

Details

Features

• Add get_host to Container and deprecate get_host_ip_address (#618)
• Allow cgroupns-mode and userns-mode to be configured (#605)

[0.16.5] - 2024-04-29

Details

Bug Fixes

• Correct drop of a network for sync container (#612)
• Correct default for get_host_ip_address in case of unix or npipe (#613)

Miscellaneous Tasks

• Update serde-java-properties to 0.2.0 (#614)

[0.16.4] - 2024-04-29

Details

Bug Fixes

• Properly expose mapped ports (#610)

Features

• Introduce properties-config cargo feature (#608)
• Support docker auth configuration for image pulling (#609)

[0.16.3] - 2024-04-27

Details

Bug Fixes

• Expose mount-related types (#603)

[0.16.2] - 2024-04-27

Details

Documentation

• Fix docsrs attributes

[0.16.1] - 2024-04-27

Details

Documentation

• Add readme to crates.io and fix documentation builds (#598)
• Fix symlink to readme (#600)

[0.16.0] - 2024-04-27

Details

Bug Fixes

• Use the binds option instead of volumes for mounts (#581)

Documentation

• Mention a way to preserve running containers (#586)

Features

• Support for docker cli flag --add-host (#547)
• Allow to override args in a RunnableImage (#558)
• Add name parameter to RunnableImage (#549)
• [❗] Container-centric API with refactored underlying layer (#575)
• Add ability to pull-image explicitly (#579)

Miscellaneous Tasks

• Remove spectral from dev-dependencies (#526)
• Update reqwest requirement from 0.11.14 to 0.12.3 (#569)
• Update bollard and bollard-stubs (#574)
• Reuse workspace level configs (#568)

Refactor

• [❗] Api for mounts and volumes (#596)

Styling

• Derive Default to fix clippy lint (#525)
• Actualize formatting configs (#567)
• Enable StdExternalCrate grouping

[0.15.0] - 2023-09-28

Added

• Added privileged parameter to RunnableImage
• Added shm_size (shared memory size) parameter to RunnableImage
• Added logging of an error when starting a container fails

Changed

• Container::exec changed to be synchronous and return ExecOutput
• MSRV is now 1.63.
• Fixed get_bridge_ip_address not to use outdated properties
• Docker trait is declared to be Send + Sync

Removed

• Removed all pre-defined images from the library to escape unbounded maintenance work. See #471 for details.
• Removed explicit support for podman. See #422 for details.

[0.14.0] - 2022-05-30

Added

• Added watchdog feature that spawns a background thread keeping track of docker containers that are started by the test suite and removes them in the case of a CTRL+C or kill of the test process.
• Introduced Container::get_host_port_ipv4, Container::get_host_port_ipv6, ContainerState::host_port_ipv4, and ContainerState::host_port_ipv6 to better handle automatically assigned ports. Docker may bind the same exposed container port to different host ports on 0.0.0.0 and ::, depending on influences from the environment.

Changed

• Container::get_host_port and ContainerState::host_port are now deprecated in favor of the new IPv4- and IPv6-specific methods.
• MSRV is now 1.60.

[0.13.0] - 2022-04-04

Added

• A new client implementation that talks to the Docker daemon via HTTP. This implementation is available as testcontainers::clients::Http and provides an async interface. As of now, this implementation is guarded behind the experimental feature-flag and not yet guaranteed to work flawlessly.
• Allow using podman CLI in addition to docker
• The TESTCONTAINERS environment variable to control what happens to containers and networks at the end of a test. The default value is remove which deletes all containers and networks that were used in the test. By setting the value to keep, containers and networks will not be deleted but kept running. You will have to stop and delete those yourself eventually.
• Upgrade default bitcoin-core image version to 0.21.0. This allows us to remove -debug for bitcoind and replace it with -startupnotify=echo .... More details on bitcoind 0.21.0 can be found here. Note: This release also removed the default wallet.
• expose_port functionality to Image trait.
• Google Cloud SDK image
• RabbitMQ image
• WaitFor::Healthcheck container ready condition, which corresponds with the healthcheck status.
• MinIO image

Changed

• How images express when a container is ready: Instead of implementing wait_until_ready, images now need to implement ready_conditions which returns a list of WaitFor instances.
• Return value of get_host_port from Option<u16> to u16. If the port cannot be resolved, this function will now panic.
• MSRV bumped to 1.46.
• Make Docker trait pub(crate). This reduces the API surface of the crate which allows for fewer breaking changes in the future. All functionality from Docker (start, stop, rm, and ports) is available on a container directly.
• descriptor is broken down into name and tag within Image trait.
• Bump MongoDB-image default version to 5.0.6.

Removed

• DYNAMODB_ADDITIONAL_SLEEP_PERIOD variable from dynamodb_local image. Previously, we had a fallback of 2 seconds if this variable was not defined. We now wait for 2 seconds unconditionally after the specified message has been found.
• Support for the KEEP_CONTAINERS env variable. The functionality of KEEP_CONTAINERS=true is superseded by TESTCONTAINERS=keep.
• with_entrypoint from the Image trait. This functionality is not used within the library. Images that need this kind of customization can always implement it on their own type directly but there is no need to force it onto them.
• Image::EnvVars and Image::Volumes associated types. The respective functions Image::env_vars and Image::volumes still exist but now return a trait object that must implement Iterator<Item = (&String, &String). This allows us to provide a default implementation which reduces the boilerplate in defining new images.
• args and with_args from Image trait.

Fixed

• Removing a docker container did not error if failed. This was fixed by asserting the daemon's response instead of just the status code: If a docker container was removed correctly using rm -f -v <ID> is printed on stdout. can either be the container name or its ID which is used within testcontainer-rs.
• Fixed clippy warnings of camel case names containing a capitalized acronym.

[0.12.0] - 2021-01-27

Added

• Allow custom version for postgres image
• Remove derivative dependency
• OrientDB image
• Zookeeper image

Changed

• Move port mapping logic to RunArgs instead of each Image.

[0.11.0] - 2020-09-30

Added

• Docker::run_with_args method. This allows naming a container and assigning it to a specific docker network. The docker network will be created if it doesn't exist yet. Once the client is dropped, the network will be removed again if it has previously been created. A network that already existed will not be removed.
• Address-type argument to coblox/bitcoin-core Image. We are setting bech32 as a default here. This is different from the default of bitcoind.

Fixed

• Block the thread until containers have been successfully removed. Previously, this was done in a fire-and-forget way and hence led to containers not being removed in certain situations.

Changed

• MSRV is now 1.41.0

[0.10.0] - 2020-08-20

Added

• Mongo image.
• Support for the fallbackfee argument for the bitcoin-core image.
• Ability to customize the entrypoint used by the image.
• Ability to start a container once stopped.

Changed

• MSRV bumped to 1.36 from 1.32.
• Change postgres image authentication POSTGRES_HOST_AUTH_METHOD rather than username and password.
• Bumped bitcoin-core default tag to 0.20.0.

[0.9.1] - 2020-03-24

Added

• A changelog
• Support volumes on containers

Changed

• Breaking: Container#get_host_port now only accepts a u16 instead of a u32. u16 captures all possible port values.

Fixes

• Provide a default password for the postgres image. There seems to be an unfortunate breaking change in the postgres image that we need to cater for.