The docs for this PR live here. All of your documentation changes will be reflected on that endpoint. The docs are available until 30 days after the last update.

Thanks for the fix @hanouticelina!

There's a related but distinct tqdm bug that this PR's _create_progress_bar would be the ideal place to fix:

tqdm crashes with multiprocessing lock errors when used in threaded contexts such as Textual TUI worker threads, some web server setups, etc.

The error looks like:

ValueError: bad value(s) in fds_to_keep

or

OSError: [Errno 9] Bad file descriptor

This happens because tqdm internally initializes multiprocessing locks during __init__, and in certain threaded environments the file descriptors aren't valid. Since _create_progress_bar is now the single entry point for creating progress bars, this is the perfect place to add this defensive measure. it would make all downloads robust in threaded contexts without any caller-side changes:

def _create_progress_bar(*, cls, log_level, name=None, **kwargs):
    # ... existing logic ...
    try:
        return cls(disable=disable, name=name, **kwargs)
    except (OSError, ValueError):
        # tqdm multiprocessing lock init can fail in threaded contexts
        # (Textual workers, some web servers). Fall back to disabled bar.
        logger.warning(
            "Progress bar could not be initialized in this environment. "
            "Download will continue without progress reporting. "
            "Set HF_HUB_DISABLE_PROGRESS_BARS=1 to silence this warning."
        )
        return cls(disable=True, **kwargs)

Right now users can work around this by setting HF_HUB_DISABLE_PROGRESS_BARS=1, or calling the disable progress bar function but a library call like hf_hub_download shouldn't crash just because the caller didn't set an env var or remember to call a function. The download itself is fine. It's only the progress bar initialization that fails. The try/except here ensures downloads work in any runtime context, and callers don't need to defensively configure their code to avoid crashes from this library.

This crash was initial root motivation behind #4051 and I feel it might as well be addressed here.

The non-TTY silencing was a secondary symptom, but the primary crash was tqdm's multiprocessing lock failing in worker threads.

My suggestion is to add this try/except and add a test case before merging. This way a separate fix/pr can be avoided and this is a great defensive measure.

@Wauplin updated the PR description and addressed your comment, thanks!

@Wauplin @hanouticelina this is the second time my concerns were ignored or dismissed silently.

My feedback on this PR was completely ignored which is troublesome. If my concerns are wrong or invalid, then they should be acknowledged and resolved and not ignored. If I'm in the wrong place, I should be told this as well. I would have never put in the effort had I known it wouldn't even be read.

I put a large amounts of effort into providing exhaustive amounts of information, reproducing bugs, creating detailed descriptions, creating a fix and they just got completely dismissed with zero acknowledgement which isn't great. Nobody should be ignored like this. A simple acknowledgement would have been sufficient. A culture of ignoring is just not cool, especially if the concerns are warranted and valid. All I asked for was to roll in a defensive measure here, and what got merged in will crash specifically in the contexts I mentioned. If my approach isn't good, then say so and be direct. My ego isn't big and I'm always prepared to be wrong about something. Could simply suggest opening a separate PR or you can tell me that my approach is bad, but the silence is why I'm raising an alarm.

It started here: #4051

my bug reports, granularity concerns, all dismissed and not acknowledged. I understand my implementation not being merged in, but all the concerns in this PR were just completely either not read or just not appreciated at all. My implementation was deemed "too complicated" but it also was a completely backwards compatible additive not breaking change and that was my philosophy. The code here is a deliberate breaking change and something I was trying to avoid introducing as an outsider to the org. I understand it not being merged in due to the complexity, but the surrounding concerns of the crash and the progress granularity being ignored is what is unsettling. A change request could have also been an option and I would have happily made the change

Most importantly, the crash concern got completely ignored in this pr.

I expect similar communication patterns with my followup

issues:
#4058
#4066

PRs:
#4059
#4065

If someone puts significant effort into something, the general rule that we all should stand by is acknowledging their concerns. In that previous PR, i identified two serious bugs, and the response was along the lines of "this is too complicated and not worth it" and I get it but there were other issues flagged in this PR that got dismissed completely which is what concerns me. This is poor communication. Suggesting a different implementation and acknowledging the issues I flagged is what I was hoping for.

You can say something like "Create a separate issue", or "this concern will be addressed in a separate PR" or "thanks for the report, but we'll be doing this differently" or even in the case of this PR, just an emoji reaction would be sufficient, but instead it got completely ignored and now I feel less compelled to report any bugs in the future. Ignoring is not acceptable and an improvement in communication is needed.

I normally do not create noise like this, but I obviously do not like being ignored and I apologize for the wall of text. My goal is to help make this library as good as it can be and work well for everyone. When serious concerns are raised and ignored, it's just baffling to me. I really appreciate this library and I can't help but call out this behavior in an effort to improve communication with those outside of the org. Like I said before, being ignored makes me not want to report these bugs anymore, so I really hope this communication issue gets addressed.

Hey @tobocop2 , thanks for your help. I've just reviewed #4059 and #4065. I understand the frustration but please don't be too pushy.