unslothai/unsloth · error · RuntimeError

S3 dataset loading requires boto3. Install it with: pip inst

Error message

S3 dataset loading requires boto3. Install it with: pip install boto3

What it means

RuntimeError raised at the top of prepare_s3_dataset_download when boto3_available() reports that the boto3 module cannot be imported. The S3 dataset loader needs boto3 at runtime but it is an optional dependency, so the environment check fails fast with an actionable install command instead of an ImportError deep in the download path.

Source

Thrown at studio/backend/core/training/s3_dataset.py:162

    if cancel_callback is not None and cancel_callback():
        raise S3DownloadCancelled("S3 dataset download cancelled")


def prepare_s3_dataset_download(
    s3_config: dict,
    dest_dir: Optional[str] = None,
    cancel_callback: Optional[Callable[[], bool]] = None,
) -> S3DatasetDownload:
    """Download supported dataset files from S3 to a local directory.

    Returns the local files plus the owned temporary directory, when one was
    created. Call ``cleanup()`` after the dataset loader has materialized data.

    Raises ``RuntimeError`` if boto3 is missing, and ``ValueError`` if the
    bucket/prefix contains no supported dataset files.
    """
    if not boto3_available():
        raise RuntimeError("S3 dataset loading requires boto3. Install it with: pip install boto3")

    bucket = s3_config.get("bucket")
    if not bucket:
        raise ValueError("s3_config.bucket is required")
    prefix = s3_config.get("prefix")

    _raise_if_cancelled(cancel_callback)
    client = _build_s3_client(s3_config)

    keys = _list_dataset_keys(client, bucket, prefix)
    _raise_if_cancelled(cancel_callback)
    if not keys:
        where = f"s3://{bucket}/{prefix}" if prefix else f"s3://{bucket}"
        raise ValueError(
            f"No supported dataset files ({', '.join(SUPPORTED_EXTENSIONS)}) "
            f"found under {where}"
        )

View on GitHub (pinned to 203007d190)

Solutions

Install boto3 into the interpreter that runs the backend: pip install boto3 (match the exact venv/container).
Verify with the same interpreter: python -c "import boto3" from the service's environment.
Add boto3 to the deployment's dependency list (requirements/lockfile/image) so rebuilds keep it.

Example fix

// before: module missing
$ python -m pip list | grep -i boto3   # nothing
// after
$ python -m pip install boto3
$ python -c "import boto3; print(boto3.__version__)"

Defensive patterns

Strategy: validation

Validate before calling

import importlib.util

assert importlib.util.find_spec('boto3') is not None, \
    "boto3 missing — install it in this interpreter: pip install boto3"

Try / catch

try:
    dl = prepare_s3_dataset_download(cfg)
except RuntimeError as e:
    if 'boto3' in str(e):
        subprocess.run([sys.executable, '-m', 'pip', 'install', 'boto3'], check=True)
        dl = prepare_s3_dataset_download(cfg)  # retry after install

Prevention

Include boto3 in the deployment's locked dependencies when S3 datasets are used.
Smoke-test `import boto3` in the service's virtualenv during deploy.
Use the same interpreter for pip and for running the backend.

When it happens

Trigger: Calling prepare_s3_dataset_download in an environment where 'import boto3' fails — boto3 never installed, installed in a different virtualenv/interpreter than the one running the backend, or a broken install (missing botocore).

Common situations: Fresh deployment without the s3 extras; training container image built without boto3; IDE or systemd service using a different Python than the shell where boto3 was pip-installed.

Related errors

AI-assisted analysis of unslothai/unsloth@203007d190 (2026-08-15). Data as JSON: /api/errors/691d21281a6cf487. Report an issue: GitHub.