huggingface / huggingface/accelerate

ACCELERATE_BYPASS_DEVICE_MAP is the only boolean env flag read case-sensitively, so =True is silently ignored

Open Beginner friendly
#4,240 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
9.9k
Forks
1.5k
Avg merge
5d 2h
Merged PRs (30d)
27

Description

### Describe the bug

`ACCELERATE_BYPASS_DEVICE_MAP` is the only boolean environment flag in `accelerate` that is read case-sensitively, so setting it to `True` silently does nothing while the identical spelling works for every sibling flag.

All three read sites in `src/accelerate/accelerator.py` compare without `.lower()`:

```python
# accelerator.py:1475, 1816, 1890
os.environ.get("ACCELERATE_BYPASS_DEVICE_MAP", "false") != "true"
```

Every other boolean flag lowercases first. Sweeping `src/accelerate` for boolean env comparisons:

| parsing | flags |
| --- | --- |
| `.lower() == "true"` | `ACCELERATE_USE_FSDP`, `ACCELERATE_USE_DEEPSPEED`, `ACCELERATE_USE_MEGATRON_LM`, `ACCELERATE_USE_SAGEMAKER`, `ACCELERATE_USE_PARALLELISM_CONFIG`, `ACCELERATE_ALLOW_CP_STANDALONE`, `ACCELERATE_DEBUG_MODE`, `ACCELERATE_DEEPSPEED_ZERO3_SAVE_16BIT_MODEL`, `FSDP_OFFLOAD_PARAMS`, `PARALLELISM_CONFIG_SP_SEQ_LENGTH_IS_VARIABLE` |
| no `.lower()` | **`ACCELERATE_BYPASS_DEVICE_MAP`** |

Ten of eleven are case-insensitive. The eleventh is the escape hatch.

### Reproduction

The expressions as written in `accelerator.py`, side by side:

```python
def bypass_active(v): # accelerator.py:1475 / 1816 / 1890
return not (v != "true")

def fsdp_active(v): # accelerator.py:381 and 9 sibling sites
return v.lower() == "true"
```

```
value BYPASS_DEVICE_MAP USE_FSDP (sibling)
'true' True True
'True' False True
'TRUE' False True
```

### Why it matters

The variable is an escape hatch, and both of the things it guards fail quietly when it is ignored:

1. `accelerator.py:1475` raises `ValueError("You can't train a model that has been loaded with device_map='auto' in any distributed mode. ...")`. A user who sets `ACCELERATE_BYPASS_DEVICE_MAP=True` still gets the exception, and the error text does not mention the variable, so there is nothing to suggest the value was the problem.
2. `accelerator.py:1890` selects DDP `device_ids` / `output_device`. Ignored here, the process silently takes the non-bypass branch.

The variable is undocumented, so it is learned from issues and discussions where capitalisation is not consistent, and `True` is the spelling a Python user reaches for first. It is also the spelling that works for `ACCELERATE_USE_FSDP` in the same file, which makes the inconsistency actively misleading rather than merely strict.

### Expected behavior

`ACCELERATE_BYPASS_DEVICE_MAP` should be read the same way as its ten siblings. Adding `.lower()` at the three sites only widens acceptance to `True` and `TRUE`, so no value that works today changes meaning.

### A related question, deliberately kept separate

None of these eleven flags accept `1`, `yes`, or `on`, even though `str_to_bool` in `utils/environment.py` is the library's own documented truth parser and accepts all of them. Routing the flags through `str_to_bool` would make the whole family consistent, but that is a larger change with a wider blast radius, so I have not folded it in here. Happy to open it separately if it is wanted.

### Checked before filing

Searched the tracker, issues and pull requests, open and closed, for `ACCELERATE_BYPASS_DEVICE_MAP` and `BYPASS_DEVICE_MAP`; nothing found. Present on `main` at f13f7c1 (v1.16.0dev), all three sites.

I have the one-line fix ready and am happy to open the PR if you would like it.

Contributor guide

Open the contributing guide

Research direction

Start in src/accelerate/accelerator.py at the three ACCELERATE_BYPASS_DEVICE_MAP reads identified at lines 1475, 1816, and 1890, and compare them with the sibling boolean flags that lowercase values. Done means True and TRUE behave like true at all three sites without changing the behavior of values accepted today.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
machine-learning
Issue type
Bug
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
85/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.