{"record":{"id":"025e3827a957a6a0","repo":"opendatalab/MinerU","slug":"s3-io-requires-optional-dependencies-install-them","errorCode":null,"errorMessage":"S3 IO requires optional dependencies. Install them with `pip install 'mineru[s3]'`.","messagePattern":"S3 IO requires optional dependencies\\. Install them with `pip install 'mineru\\[s3\\]'`\\.","errorType":"exception","errorClass":"ModuleNotFoundError","httpStatus":null,"severity":"error","filePath":"mineru/data/io/s3.py","lineNumber":11,"sourceCode":"# Copyright (c) Opendatalab. All rights reserved.\nfrom ..io.base import IOReader, IOWriter\n\n\ndef _load_s3_client_dependencies():\n    \"\"\"按需加载 S3 客户端依赖，避免导入 S3 类时强制安装 boto3。\"\"\"\n    try:\n        import boto3\n        from botocore.config import Config\n    except ImportError as exc:\n        raise ModuleNotFoundError(\n            \"S3 IO requires optional dependencies. Install them with `pip install 'mineru[s3]'`.\"\n        ) from exc\n\n    return boto3, Config\n\n\nclass S3Reader(IOReader):\n    def __init__(\n        self,\n        bucket: str,\n        ak: str,\n        sk: str,\n        endpoint_url: str,\n        addressing_style: str = 'auto',\n    ):\n        \"\"\"s3 reader client.\n\n        Args:","sourceCodeStart":1,"sourceCodeEnd":29,"githubUrl":"https://github.com/opendatalab/MinerU/blob/4fe4bde114a23ee5dd637eae99b767f4669bf58c/mineru/data/io/s3.py#L1-L29","documentation":"ModuleNotFoundError raised by _load_s3_client_dependencies() in mineru/data/io/s3.py when `import boto3` / `from botocore.config import Config` fails. Because importing the S3 classes themselves does not pull boto3 (it is loaded on demand), the failure surfaces only once an S3Reader/S3Writer actually initializes a client — typically in __init__ or the first request.","triggerScenarios":"Instantiating S3Reader/S3Writer from mineru.data.io without the [s3] extra installed; or reaching multi_bucket_s3's _load_s3_io_classes() path, which imports this module. Triggered by any first use of the S3 IO classes on a boto3-less environment.","commonSituations":"Slender Docker images built from base mineru; `pip install mineru --no-deps` style installs that skip extras; production environments where S3 support was never provisioned but paths were later switched to s3://.","solutions":["Install the extra: `pip install 'mineru[s3]'`.","Or install directly: `pip install boto3 botocore`.","Add the extra to your deployment's dependency lock so rebuilds keep it.","Confirm the fix with `python -c \"from mineru.data.io import S3Reader\"`."],"exampleFix":"# before\nfrom mineru.data.io import S3Reader  # ok (lazy)\nreader = S3Reader('bkt', 'ak', 'sk', 'http://...')  # ModuleNotFoundError\n\n# after\n# pip install 'mineru[s3]'\nreader = S3Reader('bkt', 'ak', 'sk', 'http://...')","handlingStrategy":"validation","validationCode":"def assert_s3_runtime():\n    import importlib.util\n    missing = [m for m in ('boto3', 'botocore') if importlib.util.find_spec(m) is None]\n    if missing:\n        raise SystemExit(f'missing {missing}; run: pip install \"mineru[s3]\"')\n\nassert_s3_runtime()\nfrom mineru.data.io import S3Reader, S3Writer","typeGuard":null,"tryCatchPattern":"try:\n    from mineru.data.io import S3Reader\n    reader = S3Reader(bucket, ak, sk, endpoint)\nexcept ModuleNotFoundError as e:\n    if 'mineru[s3]' in str(e):\n        raise SystemExit('pip install \"mineru[s3]\" and retry') from e\n    raise","preventionTips":["Add 'mineru[s3]' to the deployment dependency spec, not just boto3 by hand.","Smoke-test `from mineru.data.io import S3Reader` in CI for S3-enabled builds.","Keep S3 paths out of environments that lack the extra, or gate the code path on find_spec checks."],"tags":["s3","dependencies","boto3","optional-deps","lazy-import"],"backgroundTag":null,"analyzedSha":"4fe4bde114a23ee5dd637eae99b767f4669bf58c","analyzedAt":"2026-08-14T21:29:18.456Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}