hiyouga/LlamaFactory · error · RuntimeError

torch.accelerator is not available, please upgrade torch to

Error message

torch.accelerator is not available, please upgrade torch to 2.7.0 or higher.

What it means

The `requires_accelerator` decorator in the v1 accelerator helper raises this RuntimeError when `torch.accelerator` does not exist on the installed PyTorch. `torch.accelerator` is the unified device API introduced in PyTorch 2.7.0, so its absence means the v1 architecture is running on an older torch build. The check is a plain `hasattr(torch, 'accelerator')` before any decorated function (device selection, barrier, etc.) runs.

Source

Thrown at src/llamafactory/v1/accelerator/helper.py:68

@unique
class ReduceOp(StrEnum):
    SUM = "sum"
    MEAN = "mean"
    MAX = "max"
    MIN = "min"


def requires_accelerator(fn):
    """Decorator to check if torch.accelerator is available.

    Note: this api requires torch>=2.7.0, otherwise it will raise an AttributeError or RuntimeError
    """

    @wraps(fn)
    def wrapper(*args, **kwargs):
        if not hasattr(torch, "accelerator"):
            raise RuntimeError("torch.accelerator is not available, please upgrade torch to 2.7.0 or higher.")

        return fn(*args, **kwargs)

    return wrapper


def is_distributed() -> bool:
    """Check if distributed environment is available."""
    return os.getenv("RANK") is not None


def get_rank() -> int:
    """Get rank."""
    return int(os.getenv("RANK", "0"))


def get_world_size() -> int:
    """Get world size."""

View on GitHub (pinned to f28afaf635)

Solutions

1. Upgrade torch: `uv pip install -U 'torch>=2.7.0'` (pick the wheel matching your local CUDA runtime)
2. Verify with `python -c "import torch; print(torch.__version__, hasattr(torch, 'accelerator'))"` before rerunning
3. If you cannot upgrade torch, unset `USE_V1` to fall back to the v0 architecture which does not use this API

Example fix

# before
pip install torch==2.5.1  # later: USE_V1=1 llamafactory-cli train ... -> RuntimeError

# after
pip install -U 'torch>=2.7.0'

import torch

if not hasattr(torch, "accelerator"):
    raise SystemExit(f"torch {torch.__version__} lacks torch.accelerator; v1 requires torch>=2.7.0")

def supports_v1_accelerator() -> bool:
    """True when torch exposes the unified accelerator API (torch>=2.7.0)."""
    import torch
    return hasattr(torch, "accelerator")

try:
    from llamafactory.v1.accelerator import helper
    helper.get_current_device()
except RuntimeError as e:
    if "torch.accelerator" in str(e):
        raise SystemExit("Upgrade torch to >=2.7.0 or unset USE_V1") from e
    raise

When it happens

Trigger: Setting `USE_V1=1` (or using the v1 launcher) with torch < 2.7.0 installed, then touching any decorated helper function such as `get_accelerator()`, `current_device()`, or device transfer utilities in `src/llamafactory/v1/accelerator/helper.py`.

Common situations: Upgrading LlamaFactory but keeping an old torch wheel for CUDA compatibility; a fresh environment resolved to torch 2.4-2.6; mixing v0-era requirements files with the v1 code path.

Related errors

• Unknown logging level: {env_level_str}.
• The installed Transformers-KT does not provide `TrainingArgu
• megatron-bridge is required when USE_MEGATRON_BRIDGE=1. Plea
• Megatron Bridge arguments are missing. Please set USE_MEGATR
• mcore_adapter is required when USE_MCA=1. Please install `mc

AI-assisted analysis of hiyouga/LlamaFactory@f28afaf635 (2026-08-14). Data as JSON: /api/errors/03fbe3b9e2ab0933. Report an issue: GitHub.