[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

Medium Risk
Changes progress bar construction and fallback behavior across download paths; while scoped to error handling, it affects user-visible progress output and warning emission in diverse runtimes (Jupyter/TUIs/pytest).

Overview
Prevents hf_hub_download/snapshot_download from crashing when tqdm cannot initialize its multiprocessing lock (e.g. sys.stderr.fileno() is invalid) by wrapping _create_progress_bar construction in try/except (OSError, ValueError).

Introduces _SafeTqdm (threading RLock-based) as a fallback: HF’s default bar falls back with a warning and continues without progress, while custom tqdm_class fallbacks are forced disable=True to avoid corrupting caller output (e.g. TUIs). Adds regression tests covering bad fileno() and exploding custom tqdm initialization.

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