{"id":24143,"library":"oneccl","title":"Intel oneAPI Collective Communications Library (oneCCL)","description":"Intel oneAPI Collective Communications Library (oneCCL) provides an efficient implementation of communication patterns used in deep learning. Version 2022.0.0 is distributed as a runtime environment package for Python, typically used with Intel optimizations for distributed training. Release cadence is tied to Intel oneAPI annual releases.","status":"active","version":"2022.0.0","language":"python","source_language":"en","source_url":"https://github.com/oneapi-src/oneCCL","tags":["distributed computing","deep learning","intel","hpc","MPI","collective communications"],"install":[{"cmd":"pip install oneccl","lang":"bash","label":"PyPI"}],"dependencies":[],"imports":[{"note":"oneccl is a runtime package that does not provide a top-level import; the actual bindings are in oneccl_bindings.","wrong":"import oneccl","symbol":"oneccl_bindings","correct":"import oneccl_bindings as ccl"}],"quickstart":{"code":"import torch.distributed as dist\nimport oneccl_bindings as ccl\nimport os\n\n# Initialize process group with oneCCL backend\ndist.init_process_group(\n    backend='ccl',\n    init_method='env://',\n    rank=int(os.environ.get('RANK', 0)),\n    world_size=int(os.environ.get('WORLD_SIZE', 1))\n)\n\nif dist.get_rank() == 0:\n    print(\"oneCCL initialized successfully\")","lang":"python","description":"Initializes a PyTorch distributed process group using the CCL backend (oneCCL). Requires environment variables RANK, WORLD_SIZE, MASTER_ADDR, MASTER_PORT to be set."},"warnings":[{"fix":"Install oneccl_bindings via conda: conda install -c intel oneccl_bindings_pt (for PyTorch) or use the full Intel AI Kit.","message":"The pip package 'oneccl' is a runtime environment (no Python code). You must install 'oneccl_bindings' separately or use the Intel conda channel to get the actual bindings.","severity":"gotcha","affected_versions":"all"},{"fix":"Use 'import oneccl_bindings' and set backend='ccl' in torch.distributed.init_process_group.","message":"oneCCL 2022.0.0 changed backend initialization: the backend name was renamed from 'ccl' to 'ccl' (still 'ccl') but the package structure changed. Old imports from 'oneccl_bindings_for_pytorch' no longer exist.","severity":"breaking","affected_versions":">=2022.0.0"},{"fix":"Replace 'import oneccl_bindings_for_pytorch' with 'import oneccl_bindings'.","message":"The older 'oneccl_bindings_for_pytorch' package is deprecated; use the unified 'oneccl_bindings'.","severity":"deprecated","affected_versions":">=2021.3"},{"fix":"Use Linux (preferably with Intel MPI installed). For Windows, consider WSL2.","message":"oneCCL is only supported on Linux and requires MPI or a compatible runtime (e.g., Intel MPI). Windows users may encounter DLL errors.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Install the bindings: conda install -c intel oneccl_bindings_pt (for PyTorch) or use the Intel AI Kit.","cause":"The 'oneccl' pip package does not include the Python bindings; the bindings need to be installed separately.","error":"ImportError: No module named 'oneccl_bindings'"},{"fix":"Add 'import oneccl_bindings' before calling init_process_group with backend='ccl'.","cause":"Confusion between NCCL and CCL backends; PyTorch does not include CCL backend by default – it requires explicit import of oneccl_bindings.","error":"RuntimeError: Distributed package doesn't have NCCL built-in"},{"fix":"Import oneccl_bindings: import oneccl_bindings as ccl before initializing the process group.","cause":"oneCCL backend is not registered because oneccl_bindings was not imported.","error":"ValueError: Invalid backend: 'ccl'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}