1. 개요

대규모 데이터 처리나 오랜 시간이 걸리는 작업 중에는 현재 상태를 시각적으로 확인하는 것이 중요합니다. tqdm은 이러한 상황에서 진행률을 실시간으로 시각화해주는 파이썬 라이브러리입니다. 반복문 내부에서 간단히 적용만 하면, 텍스트 기반의 진전 바를 통해 얼마나 진행되었는지 쉽게 확인할 수 있습니다. 이 도구는 표준 라이브러리와 다양한 외부 라이브러리(예: pandas, requests)와도 잘 통합되며, 성능 저하가 거의 없어 대량 데이터 처리에 적합합니다.

설치는 간단합니다:

pip install tqdm

2. 주요 특징

• 사용 용이성: 한 줄 코드로 반복 작업에 진전 바 추가 가능
• 유연성: 다양한 스타일과 커스터마이징 옵션 제공
• 통합 가능성: itertools, time 등 기본 라이브러리 및 pandas, requests와 호환
• 다중 플랫폼 지원: Windows, Linux, macOS 모두에서 동작
• 고성능: 프로그램 실행 속도에 미미한 영향

3. 기본 사용법

간단한 리스트 반복 시 진행 상황 표시:

from tqdm import tqdm
import time

for i in tqdm(range(100)):
    time.sleep(0.1)

출력 예시:

100%|██████████| 100/100 [00:10<00:00, 9.57it/s]

enumerate와 함께 사용하여 인덱스 정보도 포함:

from tqdm import tqdm
import time

for idx, val in enumerate(tqdm(range(100))):
    time.sleep(0.1)

진행 상황 설명 텍스트 지정:

from tqdm import tqdm
import time

for i in tqdm(range(100), desc="처리 중"):
    time.sleep(0.1)

출력:

처리 중: 100%|██████████| 100/100 [00:10<00:00, 9.60it/s]

4. 고급 기능

4-1. 중첩 진행 바
외부 루프와 내부 루프에 각각 진행 바를 설정할 수 있으며, 내부 바는 leave=False로 설정하면 외부 바에 남아 있지 않도록 할 수 있습니다.

from tqdm import tqdm
import time

for outer in tqdm(range(3), desc="외부 루프"):
    for inner in tqdm(range(10), desc="내부 루프", leave=False):
        time.sleep(0.1)

4-2. pandas 연동
pandas의 메서드에 .progress_apply()를 사용하면, 데이터 프레임 처리 시 진행률을 표시합니다.

import pandas as pd
from tqdm import tqdm

tqdm.pandas()
df = pd.DataFrame({"value": range(1000)})
df.progress_apply(lambda x: x ** 2)

4-3. 파일 다운로드 진척률 표시
requests의 스트리밍 모드와 결합하여, 큰 파일을 다운로드할 때 현재 진행률을 보여줍니다.

import requests
from tqdm import tqdm

url = 'https://example.com/largefile.zip'
response = requests.get(url, stream=True)
total_size = int(response.headers.get('content-length', 0))

with open('largefile.zip', 'wb') as f, tqdm(
    desc='다운로드 중',
    total=total_size,
    unit='B',
    unit_scale=True,
    unit_divisor=1024,
) as progress_bar:
    for chunk in response.iter_content(chunk_size=1024):
        if chunk:
            f.write(chunk)
            progress_bar.update(len(chunk))

4-4. 진행 바 스타일 커스터마이징
bar_format 매개변수를 사용해 외관을 직접 조정할 수 있습니다.

from tqdm import tqdm
import time

for i in tqdm(range(100), bar_format="{l_bar}{bar}| {n_fmt}/{total_fmt}"):
    time.sleep(0.1)

결과:

100%|██████████| 100/100

5. 실제 적용 사례

5-1. 데이터 분석 작업
CSV 파일을 읽고 각 행을 처리하는 과정에서 진행률을 표시:

from tqdm import tqdm
import pandas as pd

df = pd.read_csv('big_data.csv')
for index, row in tqdm(df.iterrows(), total=df.shape[0], desc="데이터 처리"):
    # 처리 로직 삽입
    pass

5-2. 머신러닝 학습 과정 모니터링
에포크와 배치 단위로 진행 상황을 표시하여 학습 상태를 직관적으로 확인:

from tqdm import tqdm
import time

epochs = 3
batches = 8

for epoch in tqdm(range(epochs), desc="학습 에포크"):
    for batch in tqdm(range(batches), desc="배치", leave=False):
        time.sleep(0.05)

5-3. 파일 전송/다운로드 프로세스
실제 파일 전송 시 진행률을 실시간으로 표시해 사용자 경험을 향상시킵니다. 위의 requests 예시와 동일하게 작동합니다.