tqdm多线程共享进度条会crash或错乱，因其非线程安全：并发调用update()导致计数器、光标、缓冲区竞争；需共用实例并加锁更新，或改用tqdm.contrib.concurrent.thread_map()。
tqdm 多线程共享进度条为什么直接 crash 或显示错乱
因为 tqdm 默认实例不是线程安全的：多个线程同时调用 update() 会竞争修改内部计数器、刷新缓冲区和终端光标位置，轻则进度跳变、重叠打印，重则抛出 ValueError: I/O operation on closed file 或直接卡死。根本原因在于 tqdm 的 display() 和底层 sys.stdout.write() 调用没有加锁，且状态（如 n、last_print_n）被并发读写。
用 thread-safe tqdm 实例 + 手动锁控制更新
最直接可控的方式是：所有线程共用一个 tqdm 对象，但每次调用 update() 前加线程锁。注意不能在 with tqdm(...) as pbar: 语法块内创建锁——锁必须在 pbar 生命周期内持续有效。
- 创建
threading.Lock()实例，在主线程初始化tqdm前就准备好 - 每个工作线程中，用
lock.acquire()→pbar.update(1)→lock.release()包裹更新逻辑（推荐用with lock:自动管理） - 避免在
tqdm实例上频繁调用set_description()—— 它也非线程安全；如需动态描述，改用pbar.set_postfix_str(..., refresh=False)再手动pbar.refresh()（加锁后） - 关闭自动刷新（
leave=True, smoothing=0, miniters=1, mininterval=0）可减少竞态窗口，但不能替代锁
import threading from tqdm import tqdmpbar = tqdm(total=100, desc="Processing") lock = threading.Lock()
def worker(i):
... do work ...
with lock: pbar.update(1)threads = [threading.Thread(target=worker, args=(i,)) for i in range(100)] for t in threads: t.start() for t in threads: t.join()
pbar.close()
用 tqdm.contrib.concurrent 替代原生线程池
如果你实际是在用
concurrent.futures.ThreadPoolExecutor并想“自动”集成进度条，tqdm.contrib.concurrent提供了封装好的线程/进程安全版本，底层已内置锁和队列同步机制。
-
thread_map()是最常用接口：它把可迭代对象分发到线程池，自动维护单个进度条 - 不支持自定义线程数时动态调整
total；若任务总数未知，需先传入total=len(items)或设为None（此时禁用 ETA 和百分比） - 返回结果顺序与输入一致，但进度条更新时机由内部队列消费决定，非严格按线程完成顺序
- 不要混用
thread_map()和手动tqdm实例——它们互不感知，会导致双进度条或冲突
from tqdm.contrib.concurrent import thread_mapdef
process_item(x):
... some I/O-bound work ...
return x ** 2results = thread_map(process_item, range(100), desc="Squaring", total=100)
为什么不用 multiprocessing.Pool + tqdm？
多进程环境下不能直接共享
tqdm实例（内存隔离），而progress_bar = tqdm(...)在子进程中只是副本，更新无效。常见错误是让每个进程都创建自己的tqdm，结果打出 8 行进度条刷屏。
- 正确做法是：用
concurrent.futures.ProcessPoolExecutor+tqdm.contrib.concurrent.process_map()（同理线程版） - 或使用
logging+ 主进程轮询队列方式手动同步进度，但复杂度陡增 - 注意 Windows 下 spawn 启动方式可能导致
tqdm初始化失败，建议显式设置if __name__ == '__main__':保护
真正麻烦的从来不是加锁本身，而是忘记锁住 refresh()、set_postfix() 这类看似“只读”的操作——它们内部都会修改终端状态。只要涉及输出、计数、时间戳更新，就得进同一把锁。
