opendatalab/MinerU · error · ModuleNotFoundError

S3 IO requires optional dependencies. Install them with `pip

Error message

S3 IO requires optional dependencies. Install them with `pip install 'mineru[s3]'`.

What it means

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.

Source

Thrown at mineru/data/io/s3.py:11

# Copyright (c) Opendatalab. All rights reserved.
from ..io.base import IOReader, IOWriter


def _load_s3_client_dependencies():
    """按需加载 S3 客户端依赖，避免导入 S3 类时强制安装 boto3。"""
    try:
        import boto3
        from botocore.config import Config
    except ImportError as exc:
        raise ModuleNotFoundError(
            "S3 IO requires optional dependencies. Install them with `pip install 'mineru[s3]'`."
        ) from exc

    return boto3, Config


class S3Reader(IOReader):
    def __init__(
        self,
        bucket: str,
        ak: str,
        sk: str,
        endpoint_url: str,
        addressing_style: str = 'auto',
    ):
        """s3 reader client.

        Args:

View on GitHub (pinned to 4fe4bde114)

Solutions

1. Install the extra: `pip install 'mineru[s3]'`.
2. Or install directly: `pip install boto3 botocore`.
3. Add the extra to your deployment's dependency lock so rebuilds keep it.
4. Confirm the fix with `python -c "from mineru.data.io import S3Reader"`.

Example fix

# before
from mineru.data.io import S3Reader  # ok (lazy)
reader = S3Reader('bkt', 'ak', 'sk', 'http://...')  # ModuleNotFoundError

# after
# pip install 'mineru[s3]'
reader = S3Reader('bkt', 'ak', 'sk', 'http://...')

def assert_s3_runtime():
    import importlib.util
    missing = [m for m in ('boto3', 'botocore') if importlib.util.find_spec(m) is None]
    if missing:
        raise SystemExit(f'missing {missing}; run: pip install "mineru[s3]"')

assert_s3_runtime()
from mineru.data.io import S3Reader, S3Writer

try:
    from mineru.data.io import S3Reader
    reader = S3Reader(bucket, ak, sk, endpoint)
except ModuleNotFoundError as e:
    if 'mineru[s3]' in str(e):
        raise SystemExit('pip install "mineru[s3]" and retry') from e
    raise

When it happens

Trigger: 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.

Common situations: 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://.

Related errors

• S3 reader/writer requires optional dependencies. Install the
• `{backend}` requires local pipeline dependencies (`mineru[pi
• default_prefix must be provided
• default_bucket: {self.default_bucket} config must be provide
• the bucket_name in s3_configs: {s3_configs} must be unique

AI-assisted analysis of opendatalab/MinerU@4fe4bde114 (2026-08-14). Data as JSON: /api/errors/025e3827a957a6a0. Report an issue: GitHub.