{"id":14975,"library":"testcontainers-minio","title":"MinIO Testcontainers","description":"The `testcontainers-minio` library is a component of `testcontainers-python`, an active library designed for functional and integration testing with throwaway Docker containers. It simplifies the setup and teardown of MinIO object storage instances for tests. While `testcontainers-python` is currently at version 4.x.x, the `testcontainers-minio` module is at an early release candidate, `0.0.1rc1`. The parent project `testcontainers-python` maintains a frequent release cadence, continuously adding new features and bug fixes across its various modules.","status":"active","version":"0.0.1rc1","language":"en","source_language":"en","source_url":"https://github.com/testcontainers/testcontainers-python","tags":["testcontainers","minio","testing","integration-testing","docker","object-storage","s3-compatible"],"install":[{"cmd":"pip install testcontainers[minio]","lang":"bash","label":"Install with extras"},{"cmd":"pip install testcontainers-minio","lang":"bash","label":"Install standalone (requires testcontainers-core)"},{"cmd":"pip install minio","lang":"bash","label":"Install MinIO client (required for interaction)"}],"dependencies":[{"reason":"This library is a module of the main Testcontainers Python project.","package":"testcontainers-core","optional":false},{"reason":"The official MinIO Python SDK is required to interact with the MinIO server spun up by Testcontainers.","package":"minio","optional":false}],"imports":[{"symbol":"MinioContainer","correct":"from testcontainers.minio import MinioContainer"},{"symbol":"Minio","correct":"from minio import Minio"}],"quickstart":{"code":"import io\nfrom testcontainers.minio import MinioContainer\nfrom minio import Minio\n\n# Instantiate MinioContainer (it automatically starts on entering 'with')\nwith MinioContainer() as minio_container:\n    # Get MinIO client configuration from the container\n    minio_config = minio_container.get_config()\n    endpoint = minio_config['endpoint']\n    access_key = minio_config['access_key']\n    secret_key = minio_config['secret_key']\n\n    # Create a MinIO client instance to interact with the container\n    client = Minio(\n        endpoint,\n        access_key=access_key,\n        secret_key=secret_key,\n        secure=False  # Testcontainers MinIO usually runs on http by default\n    )\n\n    bucket_name = \"test-bucket\"\n    object_name = \"hello.txt\"\n    file_content = b\"Hello from Testcontainers MinIO!\"\n\n    # Create a bucket if it doesn't exist\n    if not client.bucket_exists(bucket_name):\n        client.make_bucket(bucket_name)\n        print(f\"Bucket '{bucket_name}' created.\")\n\n    # Upload an object\n    client.put_object(\n        bucket_name,\n        object_name,\n        io.BytesIO(file_content),\n        length=len(file_content),\n        content_type=\"text/plain\"\n    )\n    print(f\"Object '{object_name}' uploaded to '{bucket_name}'.\")\n\n    # Retrieve the object\n    response = client.get_object(bucket_name, object_name)\n    retrieved_data = response.read()\n    response.close()\n    response.release_conn()\n\n    print(f\"Retrieved data: {retrieved_data.decode('utf-8')}\")\n    assert retrieved_data == file_content\n    print(\"MinIO Testcontainers setup successful!\")","lang":"python","description":"This quickstart demonstrates how to use `MinioContainer` to spin up a MinIO server, retrieve its connection details, and then use the `minio` client library to create a bucket, upload an object, and retrieve it. The container is automatically managed (started and stopped) using a `with` statement."},"warnings":[{"fix":"Consult the `testcontainers-python` CHANGELOG on GitHub for specific module changes before upgrading.","message":"Community modules like `testcontainers-minio` do not strictly follow SemVer. Breaking changes might occur in minor versions without a major version bump, unlike `testcontainers-core`. Always review the changelog for `testcontainers-python` when upgrading to new minor versions.","severity":"gotcha","affected_versions":"All versions of testcontainers-minio"},{"fix":"Create a new `minio.Minio` client object within each process where it's needed.","message":"The `minio` client object is thread-safe but not process-safe. Do not share a single `Minio` client instance across multiple processes (e.g., using `multiprocessing.Pool`), as this can lead to unexpected behavior or errors. Instead, create a new `Minio` client instance in each separate process.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure `MinioContainer` methods that construct a `Minio` client use keyword arguments for `access_key`, `secret_key`, etc., or update `minio` client calls if directly instantiating.","message":"As of `testcontainers-python` v4.14.0, the `minio` client initialization in `MinioContainer` methods (like `get_client()`) may require keyword arguments. Older code expecting positional arguments might break.","severity":"breaking","affected_versions":">=4.14.0 of testcontainers-python (parent library)"},{"fix":"Migrate custom wait strategies to use the new `ExecWaitStrategy` or other `WaitStrategy` implementations where applicable.","message":"In `testcontainers-python` v4.14.0, deprecated decorators for wait strategies (e.g., `wait_for_logs`) were replaced with new `WaitStrategy` classes. If you were using custom or older wait patterns, they might need updating.","severity":"deprecated","affected_versions":">=4.14.0 of testcontainers-python (parent library)"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure `client.make_bucket(bucket_name)` is called and completes successfully before attempting object operations on that bucket.","cause":"Attempting to put or get an object from a MinIO bucket that has not yet been created.","error":"minio.error.S3Error: S3 operation failed; No such bucket: test-bucket"},{"fix":"Verify the image name and tag are correct (e.g., `minio/minio:RELEASE.2022-12-02T19-19-22Z`). Check Docker connectivity and ensure you are logged into Docker Hub if using private repositories. Run `docker pull minio/minio:RELEASE.2022-12-02T19-19-22Z` manually to diagnose.","cause":"Docker daemon cannot pull the specified MinIO image. This often indicates a network issue, an incorrect image name/tag, or insufficient Docker permissions/authentication.","error":"docker.errors.ImageNotFound: 404 Client Error for http+docker://localhost/v1.xx/images/create?fromImage=minio/minio&tag=RELEASE.2022-12-02T19-19-22Z: Not Found (\"pull access denied for minio/minio, repository does not exist or may require 'docker login': denied: requested access to the resource is denied\")"},{"fix":"Upgrade the `minio` client library to a recent version (`pip install --upgrade minio`). Alternatively, remove the `secure` argument if your MinIO instance is HTTP-only and the client's default behavior is to infer security.","cause":"This typically means an older version of the `minio` client library is installed that does not accept the `secure` keyword argument, or there's a mismatch between the expected arguments and the installed client version.","error":"TypeError: Minio() got an unexpected keyword argument 'secure'"}],"ecosystem":"pypi"}