NUMA Binding Utilities

Created On: Jul 25, 2025 | Last Updated On: Jul 25, 2025

class torch.distributed.numa.binding.AffinityMode(value)

See behavior description for each affinity mode in torch.distributed.run.

class torch.distributed.numa.binding.NumaOptions(affinity_mode: torch.distributed.numa.binding.AffinityMode, should_fall_back_if_binding_fails: bool = False)

affinity_mode: AffinityMode

If true, we will silently return the original command if any of the following occur: - An exception is raised as we compute the wrapped command. - During a dry run of the wrapped command, numactl fails for any reason.

You should avoid using this option! It is only intended as a safety mechanism for facilitating mass rollouts of numa binding.

torch.distributed.numa.binding.maybe_wrap_with_numa_bindings(*, entrypoint, local_rank_to_args, numa_options)

Parameters

• entrypoint (str) – The entrypoint to the program, such as might be input to Popen. Example: “python”

• local_rank_to_args (dict[int, tuple]) – A mapping from local rank to args for the entrypoint. Example: {0: (“trainer.py”,)}

• numa_options (Optional[NumaOptions]) – See NumaOptions for details.

Returns

A tuple of (entrypoint, local_rank_to_args), basically transforming the inputs, where the entrypoint and args may now involve numa binding. Example: (“numactl”, {“0”: (“–cpunodebind=0”, “–preferred=0”, “python”, “trainer.py”)})

Return type

tuple[str, dict[int, tuple]]