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 tqdm 
pbar = 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_map 
def process_item(x):
... some I/O-bound work ...
return x ** 2
results = 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() 这类看似“只读”的操作——它们内部都会修改终端状态。只要涉及输出、计数、时间戳更新，就得进同一把锁。