[BUG FIX]: hf_hub_download crashes when stderr lacks a real file descriptor

[tobocop2]

Problem

hf_hub_download crashes with ValueError: bad value(s) in fds_to_keep in any environment where sys.stderr is not backed by a real file descriptor.

The download itself is fine. Only tqdm's progress bar initialization fails, but because _create_progress_bar has no safety net, it takes down the entire download.

Affected environments

Any runtime where sys.stderr is not backed by a real file descriptor:

• Textual TUI apps
• Jupyter notebooks
• pytest capture
• WSGI/ASGI web servers (gunicorn, uvicorn)
• Sandboxed/containerized runtimes
• IDE embedded terminals

Root cause

_create_progress_bar calls cls(disable=disable, name=name, **kwargs) with no exception handling. When stderr's fileno() returns -1, tqdm's __init__ tries to create a multiprocessing lock, which spawns a resource tracker subprocess via fork_exec(), which rejects the invalid fd.

Crash Demo

Fix

Add a _SafeTqdm subclass that uses a threading.RLock instead of a multiprocessing lock, and wrap both cls() calls in _create_progress_bar with try/except (OSError, ValueError) to fall back to _SafeTqdm.

Fixes #4066

---

Note

Low Risk
Change is limited to progress-bar creation error handling and test coverage; it only activates on tqdm initialization failures and otherwise preserves existing behavior.

Overview
Prevents downloads from crashing when tqdm progress bar initialization fails (notably when sys.stderr lacks a valid file descriptor) by wrapping progress-bar construction in try/except and falling back to a disabled _SafeTqdm that uses a thread lock.

Adds a user warning for the default HF tqdm path when progress reporting is unavailable, and extends tests to cover the bad-fileno scenario and verify that both custom and HF tqdm_class failures degrade to disable=True (without emitting pytest unraisable destructor warnings).

^{Reviewed by Cursor Bugbot for commit 2e89815. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 59aa035. Configure here.}