اگر تا حالا با ماژول logging استاندارد پایتون کار کرده باشید، می‌دانید که برای یک لاگ ساده هم باید handler و formatter و level تعریف کنید؛ Loguru آمد تا همین کار را در یک خط انجام دهد. این کتابخانه‌ی سبک و محبوب، لاگ‌های رنگی، چرخش خودکار فایل و رهگیری کامل خطا را بدون تنظیمات پیچیده به شما می‌دهد و برای اسکریپت‌های کوچک تا سرویس‌های پروداکشن انتخابی ایده‌آل است.

Loguru چیست و چرا جایگزین logging استاندارد پایتون است؟

Loguru یک کتابخانه‌ی لاگ‌گیری مدرن برای پایتون است که با یک import ساده، لاگ‌های رنگی در ترمینال، ذخیره خودکار در فایل با rotation و نمایش کامل traceback را فعال می‌کند؛ برخلاف logging استاندارد نیازی به ساختن Logger و Handler ندارد و با یک خط logger.add() همه‌چیز آماده است. در ادامه نصب، فرمت‌دهی و ترفندهای پروداکشن را قدم‌به‌قدم می‌بینید.

فهرست مطالب

پیش‌نیازها و نصب Loguru
اولین لاگ با Loguru در ۳۰ ثانیه
سطوح لاگ و فرمت‌بندی رنگی در Loguru
تنظیم فرمت شخصی و رنگ‌ها
ذخیره همزمان در کنسول و فایل با چرخش خودکار
رهگیری خطاها و لاگ استثناها با Loguru
مقایسه Loguru با logging و structlog
اشتباهات رایج هنگام کار با Loguru
سوالات متداول
جمع‌بندی

پیش‌نیازها و نصب Loguru

برای شروع فقط به پایتون ۳.۸ به بالا و pip نیاز دارید. Loguru هیچ وابستگی خارجی ندارد، بنابراین در هر محیط مجازی، روی لپ‌تاپ شخصی یا سرور لینوکسی به‌راحتی نصب می‌شود. اگر از محیط‌هایی مثل venv یا uv استفاده می‌کنید، کافی است محیط را فعال کنید و دستور نصب را بزنید.

pip install loguru
# یا با uv
uv pip install loguru

بعد از نصب، نسخه را چک کنید تا مطمئن شوید نصب درست انجام شده است:

python -c "import loguru; print(loguru.__version__)"

نکته‌ی مهم: Loguru به‌صورت پیش‌فرض یک sink کنسول با رنگ دارد؛ یعنی حتی بدون هیچ تنظیم اضافه، لاگ‌های شما خوانا و رنگی نمایش داده می‌شوند. اگر پروژه‌تان از قبل از logging استفاده می‌کند، می‌توانید به‌تدریج مهاجرت کنید و حتی لاگ‌های کتابخانه‌های دیگر را با intercept handler به Loguru هدایت کنید.

اولین لاگ با Loguru در ۳۰ ثانیه

سادگی Loguru را در همین مثال اول می‌بینید. کافی است logger را import کنید و مستقیم لاگ بزنید:

from loguru import logger

logger.debug("این یک پیام دیباگ است")
logger.info("سرویس با موفقیت اجرا شد")
logger.warning("حافظه در حال پر شدن است")
logger.error("اتصال به دیتابیس失敗")
logger.critical("سرویس از دسترس خارج شد!")

خروجی در ترمینال به‌صورت رنگی با زمان، سطح و پیام نمایش داده می‌شود، مثل:

2026-09-01 15:30:12 | INFO     | __main__:4 - سرویس با موفقیت اجرا شد

برای افزودن لاگ به فایل، فقط یک خط اضافه کنید؛ نیازی به FileHandler نیست:

from loguru import logger

logger.add("app.log", rotation="10 MB", retention="7 days", compression="zip")
logger.info("این پیام هم در کنسول و هم در فایل ذخیره می‌شود")

همین یک خط، فایل را می‌سازد، وقتی به ۱۰ مگابایت رسید یک فایل جدید می‌سازد و فایل‌های قدیمی‌تر از ۷ روز را پاک می‌کند. اگر روی پروژه‌های هوش مصنوعی کار می‌کنید و می‌خواهید لاگ‌های اجرای مدل را همزمان تحلیل کنید، ابزارهایی مثل Claude 4.5 Opus با جهش در استدلال و کدنویسی می‌توانند در کنار لاگ‌های تمیز Loguru، دیباگ را چند برابر سریع‌تر کنند.

سطوح لاگ و فرمت‌بندی رنگی در Loguru

Loguru از همان سطوح استاندارد TRACE, DEBUG, INFO, SUCCESS, WARNING, ERROR, CRITICAL پشتیبانی می‌کند، با این تفاوت که یک سطح اضافه به نام TRACE (شماره ۵) و SUCCESS (شماره ۲۵) هم دارد. TRACE برای جزئی‌ترین لاگ‌های توسعه و SUCCESS برای تأیید عملیات موفق بدون اینکه WARNING باشد، عالی است.

from loguru import logger

logger.trace("مقدار متغیر x = {}", 42)
logger.success("پردازش ۱۵۰۰ رکورد با موفقیت تمام شد")

برای کنترل سطح نمایش، کافی است هنگام add کردن، پارامتر level را بدهید:

logger.add("debug.log", level="DEBUG")
logger.add("error.log", level="ERROR")

به این ترتیب می‌توانید لاگ‌های DEBUG را فقط در یک فایل و لاگ‌های ERROR را در فایل جدا نگه دارید، بدون اینکه کد اصلی شلوغ شود.

تنظیم فرمت شخصی و رنگ‌ها

فرمت پیش‌فرض Loguru خواناست، اما برای پروداکشن معمولاً می‌خواهید زمان را ISO کنید، نام ماژول و شماره خط را اضافه کنید یا حتی JSON لاگ بگیرید. پارامتر format با سینتکس {time} {level} {message} این کار را می‌کند و تگ‌های رنگی مثل <green> هم پشتیبانی می‌شود.

from loguru import logger
import sys

logger.remove()
logger.add(sys.stderr, format="{time:YYYY-MM-DD HH:mm:ss} | {level: <8} | {name}:{function}:{line} - {message}")

logger.info("فرمت شخصی با رنگ فعال شد")

اگر می‌خواهید لاگ را برای ELK یا Loki به‌صورت JSON بفرستید، از serialize=True استفاده کنید:

logger.add("app.json", serialize=True)
logger.info("کاربر وارد شد", user="ali", ip="192.168.1.10")

خروجی JSON شامل time, level, message, extra و exception خواهد بود و مستقیم برای تحلیل آماده است.

ذخیره همزمان در کنسول و فایل با چرخش خودکار

قدرت واقعی Loguru در مدیریت فایل است. سه پارامتر کلیدی rotation, retention و compression همه‌چیز را خودکار می‌کنند:

rotation: شرط ساخت فایل جدید؛ مثل "500 MB"، "12:00" (هر روز ظهر) یا "1 week"
retention: مدت نگهداری؛ مثل "10 days" یا تعداد فایل "5 files"
compression: فشرده‌سازی خودکار فایل‌های قدیمی؛ "zip" یا "gz"

from loguru import logger

logger.add(
    "logs/app_{time:YYYY-MM-DD}.log",
    rotation="00:00",
    retention="30 days",
    compression="gz",
    level="INFO",
    encoding="utf-8"
)
logger.info("لاگ روزانه با فشرده‌سازی خودکار")

همچنین می‌توانید با filter فقط لاگ‌های یک ماژول را به یک فایل بفرستید:

logger.add("payment.log", filter=lambda record: record["name"] == "payment")
logger.add("api.log", filter=lambda record: "api" in record["name"])

این تفکیک بدون ساختن چند Logger مختلف انجام می‌شود و کد تمیز می‌ماند.

رهگیری خطاها و لاگ استثناها با Loguru

یکی از دلایلی که توسعه‌دهندگان از logging استاندارد خسته می‌شوند، tracebackهای ناقص است. Loguru با logger.exception و دکوراتور @logger.catch این مشکل را حل می‌کند.

from loguru import logger

@logger.catch
def divide(a, b):
    return a / b

divide(10, 0)
# traceback کامل با مقادیر متغیرها لاگ می‌شود

برای try/except دستی هم کافی است:

try:
    1 / 0
except ZeroDivisionError:
    logger.exception("خطا در محاسبه")
    # یا
    logger.opt(exception=True).error("خطای محاسباتی رخ داد")

اگر می‌خواهید مقادیر متغیرها را در traceback ببینید، از diagnose=True و backtrace=True استفاده کنید (فقط در محیط توسعه، چون اطلاعات حساس را نشان می‌دهد):

logger.add("error.log", diagnose=True, backtrace=True)

نکته امنیتی: در پروداکشن diagnose را False بگذارید تا رمزها و توکن‌ها در لاگ نماند.

مقایسه Loguru با logging و structlog

برای انتخاب ابزار لاگ، این جدول به شما کمک می‌کند سریع تصمیم بگیرید. اگر پروژه‌تان کوچک تا متوسط است و می‌خواهید سریع به نتیجه برسید، Loguru برنده است؛ اگر نیاز به سازگاری کامل با اکوسیستم logging دارید، logging استاندارد؛ و اگر لاگ ساخت‌یافته JSON برای تحلیل توزیعی می‌خواهید، structlog گزینه‌ی حرفه‌ای‌تر است.

ویژگی	Loguru	logging استاندارد	structlog
نصب و راه‌اندازی	۱ خط، بدون handler	نیاز به Logger/Handler/Formatter	نیاز به پیکربندی processor
رنگ در ترمینال	پیش‌فرض	با کتابخانه جانبی	با processor رنگ
چرخش فایل	rotation/retention داخلی	RotatingFileHandler دستی	ندارد (خودتان بسازید)
سریال JSON	serialize=True	با Formatter سفارشی	ذاتی و قدرتمند
رهگیری خطا	@logger.catch عالی	logger.exception محدود	خوب
کارایی	بسیار خوب	خوب	عالی برای حجم بالا

اگر به دنبال الهام برای تصویرسازی لاگ‌ها یا حتی ساخت پرامپت‌های بصری برای مستندسازی هستید، نمونه‌های خلاقانه‌ای مثل پرامپت عکس ساحلی روی اسکله در غروب طلایی نشان می‌دهد چطور یک پرامپت دقیق می‌تواند خروجی را متحول کند — همین دقت را در فرمت لاگ هم به کار ببرید.

اشتباهات رایج هنگام کار با Loguru

فراموش کردن logger.remove(): اگر دوباره logger.add(sys.stderr, ...) بزنید بدون remove، لاگ‌ها دو بار چاپ می‌شوند. همیشه اول logger.remove() بزنید سپس add جدید.
استفاده از diagnose در پروداکشن: این گزینه مقادیر متغیرهای محلی را در لاگ می‌نویسد و ممکن است رمز عبور یا توکن را لو بدهد. فقط در توسعه True کنید.
فرمت‌دهی با f-string اشتباه: به‌جای logger.info(f"value {x}") از logger.info("value {}", x) استفاده کنید تا lazy formatting و کارایی بهتر باشد و extra به JSON اضافه شود.
ذخیره فایل بدون encoding: اگر پیام فارسی دارید، حتماً encoding="utf-8" بدهید وگرنه روی ویندوز کاراکترها به‌هم می‌ریزد.
عدم مدیریت retention: اگر retention ندهید، دیسک پر می‌شود. حتماً برای هر فایل لاگ یک retention مثل "7 days" یا "10 files" تعریف کنید.

سوالات متداول

آیا Loguru جایگزین کامل logging استاندارد است؟

برای ۹۰٪ پروژه‌ها بله. Loguru سبک، سریع و کافی است و حتی می‌تواند لاگ‌های کتابخانه‌هایی که از logging استفاده می‌کنند را با یک interceptor جذب کند. فقط اگر به handlerهای بسیار خاص logging (مثل SysLogHandler سفارشی) نیاز دارید، logging را نگه دارید یا هر دو را ترکیب کنید.

چطور لاگ‌های کتابخانه‌های دیگر را به Loguru هدایت کنم؟

یک handler واسط بسازید که رکوردهای logging را به Loguru بفرستد:

import logging
from loguru import logger

class InterceptHandler(logging.Handler):
    def emit(self, record):
        logger_opt = logger.opt(depth=6, exception=record.exc_info)
        logger_opt.log(record.levelname, record.getMessage())

logging.basicConfig(handlers=[InterceptHandler()], level=0)

بعد از این، هر کتابخانه‌ای که با logging لاگ بزند، خروجی‌اش در Loguru با فرمت یکسان دیده می‌شود.

چطور لاگ را همزمان به کنسول، فایل و سرویس خارجی بفرستم؟

کافی است چند logger.add با sinkهای مختلف اضافه کنید؛ حتی می‌توانید یک تابع سفارشی به‌عنوان sink بدهید که به HTTP API بفرستد. هر sink سطح و فرمت خودش را دارد و مستقل کار می‌کند.

تفاوت logger.info و logger.opt چیست؟

logger.opt یک logger موقت با گزینه‌های اضافه می‌سازد، مثل exception=True برای traceback، colors=True برای رنگ اجباری یا lazy=True. خود logger.info فقط پیام را با تنظیمات پیش‌فرض می‌فرستد.

آیا Loguru برای پروژه‌های async و FastAPI مناسب است؟

بله. Loguru thread-safe است و با async هم کار می‌کند، فقط لاگ‌گیری ذاتاً sync است و برای حجم بسیار بالا بهتر است از enqueue=True استفاده کنید تا لاگ‌ها در thread جدا نوشته شوند و event loop بلاک نشود:

logger.add("app.log", enqueue=True)

جمع‌بندی

Loguru ثابت کرد که لاگ‌گیری حرفه‌ای نباید پیچیده باشد. با یک نصب ساده، یک خط برای فایل چرخشی و یک دکوراتور برای رهگیری خطا، هم کد تمیزتر می‌ماند و هم دیباگ سریع‌تر می‌شود.

نصب را با pip install loguru انجام دهید و محیط مجازی را فعال نگه دارید
اول logger.remove() بزنید و سپس sinkهای کنسول و فایل با rotation و retention تعریف کنید
برای پروداکشن encoding="utf-8" و enqueue=True را فراموش نکنید
از @logger.catch و logger.exception برای traceback کامل استفاده کنید، اما diagnose را در پروداکشن خاموش بگذارید
اگر نیاز به JSON دارید، serialize=True را فعال کنید و لاگ‌ها را به ELK یا فایل JSON بفرستید
برای مهاجرت تدریجی، InterceptHandler را اضافه کنید تا لاگ‌های قدیمی هم یکدست شوند

حالا نوبت شماست: یک اسکریپت کوچک بسازید، لاگ رنگی و فایل چرخشی را تست کنید و ببینید چقدر زمان دیباگ‌تان کم می‌شود. اگر این آموزش برایتان مفید بود، آن را با هم‌تیمی‌های پایتون‌کارتان به اشتراک بگذارید.

آموزش Loguru در پایتون؛ لاگ‌گیری حرفه‌ای بدون پیچیدگی