Python最强日志打印库loguru安装到高级用法逐步详解

聊到Python的日志处理，现在大家首选的工具应该就是loguru了。这个库主打的就是“开箱即用”，目标很明确——替代Python标准库里那个用起来有点繁琐的logging模块。它用了一个全局的logger对象，把日志记录这件事变得异常简单，同时支持多种输出目标、日志旋转、异常捕获这些高阶功能。接下来，让我们从最基础的安装开始，一步步解锁它的高级特性。

一、Python日志打印库loguru详解

1、 介绍

loguru由Delgan开发，核心理念就是“开箱即用”。说白了，就是让你少写那些重复的日志配置代码。跟Python内置的logging模块相比，它最大的优点是不用再费劲去配置各种handler。主要优点很明确： * **简洁性**：一行代码就能搞定日志处理器。 * **灵活性**：自定义格式、过滤器和输出目标，都支持得很好。 * **易用性**：异常捕获和上下文管理这些功能都是内置的，用起来非常顺手。 无论是小脚本还是大型项目，loguru都能高效处理日志。

2、安装

安装过程没什么好说的，老规矩，一条pip命令搞定：

pip install loguru

装完之后，直接在你的Python脚本里导入就能用了。

3、基本用法

loguru上手最爽的地方就在于，导入后直接用，不需要任何额外配置。默认情况下，日志会输出到标准错误流（stderr），而且已经带上了时间戳、日志级别这些关键信息。 * **导入logger**：

from loguru import logger

* **记录日志**： loguru支持标准的日志级别：DEBUG、INFO、WARNING、ERROR 和 CRITICAL。直接调用对应的方法就行：

logger.debug("这是一条调试信息")
logger.info("这是一条普通信息")
logger.warning("这是一条警告信息")
logger.error("这是一条错误信息")
logger.critical("这是一条严重错误信息")

跑一下这段代码，控制台就会输出日志，格式类似：[2023-10-05 12:34:56] INFO: 这是一条普通信息。 * **日志级别控制**： 默认情况下，所有级别的日志都会被输出（因为默认级别是DEBUG）。但你可以调整级别，比如只记录INFO及以上的：

logger.remove()  # 移除默认处理器
logger.add(sys.stderr, level="INFO")  # 添加新处理器，设置级别为INFO

这里logger.remove()是用来清除默认配置的，logger.add()则是添加自定义处理器的入口。

4、配置输出目标

日志只写在控制台肯定不够，loguru允许你添加多个处理器，把日志同时输出到文件、控制台，甚至网络服务。核心就是靠logger.add()这个方法。 * **输出到文件**： 最简单的文件日志配置，一行代码：

logger.add("app.log")  # 日志输出到app.log文件

日志文件会自动创建，内容是追加的。 * **日志旋转**： 文件一直写下去，肯定会越来越大。loguru内置了日志旋转功能，可以按时间或者按文件大小自动切割。这是非常实用的功能：

# 按文件大小旋转：当文件超过1MB时，创建新文件，最多保留3个备份
logger.add("app.log", rotation="1 MB", retention=3)

# 按时间旋转：每天午夜旋转日志
logger.add("app.log", rotation="00:00")

rotation参数指定旋转条件，retention参数控制保留多少个备份文件。 * **输出到控制台**： 默认已经输出到stderr了，但如果你想自定义格式，可以这样写：

logger.add(sys.stdout, format="{time} | {level} | {message}")

format参数里可以塞进时间、级别、消息这些基础信息，还能加上进程ID、线程ID，甚至用花括号指定时间格式。

5、 日志格式化和过滤器

loguru提供了强大的格式化能力，你可以随心所欲地自定义消息结构，还能添加上下文信息。 * **自定义格式**： 除了基本格式，你还可以加上{process}（进程ID）、{thread}（线程ID）等变量。比如：

logger.add("app.log", format="{time} | {level} | {process} | {thread} | {message}")

可用的变量包括：{time}（时间戳）、{level}（日志级别）、{message}（日志消息）、{file}（文件名）、{line}（代码行号）、{function}（函数名）。甚至可以用{time:YYYY-MM-DD HH:mm:ss}这种格式字符串来精确控制时间的显示。 * **添加过滤器**： 过滤器就像个阀门，只有符合条件的日志才能通过。比如，你只想记录消息里包含“important”的日志：

def my_filter(record):
    return "important" in record["message"]  # 只包含消息中带"important"的日志
logger.add("app.log", filter=my_filter)

这里的record是一个字典，包含了日志的所有信息。

6、 高级特性

loguru还有一些高阶功能，能让日志记录更实用、更可靠。 * **异常捕获**： 这是最实用的功能之一。用@logger.catch装饰器，函数里的异常会被自动捕获，并记录详细的堆栈信息，排查问题非常方便：

@logger.catch
def risky_function():
    return 1 / 0  # 会触发异常

risky_function()

当异常发生，loguru会记下错误消息和完整的堆栈跟踪。 * **上下文变量**： 可以给日志打上额外的标签，比如用户名、请求ID，这在多用户系统里特别有用。用bind()方法：

logger.add("app.log", format="{extra[user]} | {message}")

user_logger = logger.bind(user="admin")  # 绑定用户上下文
user_logger.info("用户登录成功")  # 输出: admin | 用户登录成功

* **异步日志**： 如果担心日志写入拖慢主程序的速度，可以开启异步队列：

logger.add("app.log", enqueue=True)  # 启用异步队列

设置enqueue=True后，日志写入不会阻塞主线程，性能会有明显提升。 * **自定义处理器**： 除了文件和控制台，你还可以把日志发送到远程服务器。写一个自定义的“sink”函数就行：

def custom_sink(message):
    # 模拟发送到网络
    print(f"发送日志: {message}")

logger.add(custom_sink)

7、代码示例

下面是一个完整的示例，囊括了配置、使用和异常捕获：

from loguru import logger
import sys

# 配置日志：输出到文件和控制台，设置格式和旋转
logger.remove()  # 移除默认处理器
logger.add("app.log", rotation="1 MB", retention=3, format="{time} | {level} | {message}")
logger.add(sys.stdout, format="{time} | {level} | {message}")

# 记录不同级别日志
logger.info("应用程序启动")
logger.warning("磁盘空间不足")

# 使用异常捕获
@logger.catch
def divide(a, b):
    return a / b

try:
    divide(10, 0)
except Exception:
    logger.error("发生除法错误")

# 添加上下文
user_logger = logger.bind(user="Alice")
user_logger.info("用户操作完成")

8、与标准库logging比较

loguru和标准库logging比起来，优势非常直观： * **配置简化**：不用再创建什么handlers、formatters、filters，一行logger.add()全部搞定。 * **API直观**：全局logger对象拿来就用，学习成本极低。 * **功能丰富**：日志旋转、异常捕获这类功能都是内置的，不需要额外找第三方扩展。 但话说回来，如果你的项目对日志架构有极其复杂的自定义需求，标准库logging可能会更合适。不过对绝大多数场景来说，loguru已经绰绰有余了。

9、总结

loguru是一个非常高效的Python日志库，尤其适合快速开发和日常维护。通过上述详解，它的核心功能应该已经清楚了： * 基本日志记录和级别控制。 * 输出目标配置（文件、控制台）。 * 高级特性如日志旋转、异常捕获和上下文绑定。

二、代码示例

1、源码分享

下面是一个更贴近实战的完整示例，包含了复杂格式、多文件输出、动态级别修改、多线程测试等场景，可以直接拿去用：

import sys
from loguru import logger
from datetime import datetime
import threading
import time

# -------------------------- 1. 自定义日志格式（复杂格式） --------------------------
# 格式说明：时间 | 进程ID | 线程名 | 日志级别 | 模块名 | 函数名 | 日志内容
LOG_FORMAT = (
    "{time:YYYY-MM-DD HH:mm:ss.SSS} | "
    "{process.id} | "
    "{thread.name} | "
    "{level: <8} | "
    "{name}:{function}:{line} - "
    "{message}"
)

# -------------------------- 2. 配置多文件日志输出（分级别/分场景） --------------------------
# 清空默认控制台输出（按需保留）
logger.remove()

# 2.1 控制台输出：彩色日志，只输出 INFO 及以上级别
logger.add(
    sink=sys.stdout,
    format=LOG_FORMAT,
    level="INFO",
    enqueue=True,  # 异步输出，提升性能
    colorize=True  # 彩色日志
)

# 2.2 错误日志单独文件：只保存 ERROR/CRITICAL 级别，自动压缩
logger.add(
    sink="logs/error_{time:YYYY-MM-DD}.log",  # 按天分割文件
    format=LOG_FORMAT,
    level="ERROR",
    encoding="utf-8",
    rotation="00:00",  # 每天凌晨分割新文件
    retention="30 days",  # 保留30天日志
    compression="zip",  # 旧日志自动压缩为zip
    enqueue=True,
    backtrace=True,  # 完整异常堆栈
    diagnose=True  # 开发环境开启变量诊断，生产环境建议关闭
)

# 2.3 全量日志文件：保存所有级别日志，文件大小超过100MB自动分割
logger.add(
    sink="logs/all_{time:YYYY-MM-DD}.log",
    format=LOG_FORMAT,
    level="DEBUG",
    encoding="utf-8",
    rotation="100 MB",  # 按文件大小分割
    retention="15 days",
    enqueue=True
)


# -------------------------- 3. 自定义日志过滤（精准过滤日志） --------------------------
def filter_debug_only(record):
    """仅保留DEBUG级别日志"""
    return record["level"].name == "DEBUG"


# 单独保存DEBUG级别日志
logger.add(
    sink="logs/debug.log",
    format=LOG_FORMAT,
    filter=filter_debug_only,
    encoding="utf-8",
    enqueue=True
)

# -------------------------- 4. 上下文绑定（统一添加日志字段） --------------------------
# 全局绑定公共字段：请求ID、用户ID
logger = logger.bind(request_id="REQ_123456", user_id="UID_789")


# -------------------------- 5. 高级功能：异常捕获、结构化日志、多线程测试 --------------------------
def demo_business_logic(num: int):
    """模拟业务逻辑"""
    try:
        # 分级日志打印
        logger.debug(f"开始执行业务逻辑，参数: {num}")
        logger.info(f"业务逻辑执行中，当前时间: {datetime.now()}")

        if num < 0:
            # 手动抛出异常，测试异常日志
            raise ValueError("数字不能为负数！")

        # 结构化日志（JSON格式，方便日志平台解析）
        logger.bind(biz_type="order").info("订单创建成功", extra={"order_id": "ORDER_001", "amount": 99.9})

        logger.success("业务逻辑执行完成✅")
    except Exception as e:
        # 自动捕获完整异常堆栈
        logger.exception("业务逻辑执行失败：")


def multi_thread_test():
    """多线程日志测试"""
    threads = []
    for i in range(3):
        t = threading.Thread(target=demo_business_logic, args=(i,), name=f"Thread-{i}")
        threads.append(t)
        t.start()

    # 测试异常线程
    error_thread = threading.Thread(target=demo_business_logic, args=(-1,), name="Thread-Error")
    error_thread.start()

    for t in threads:
        t.join()
    error_thread.join()


# -------------------------- 6. 日志级别动态修改 --------------------------
def change_log_level(new_level: str):
    """动态修改日志级别"""
    logger.remove()
    # 重新添加处理器，修改level参数
    logger.add(sys.stdout, format=LOG_FORMAT, level=new_level, colorize=True)
    logger.add("logs/error.log", format=LOG_FORMAT, level="ERROR", encoding="utf-8")
    logger.info(f"日志级别已修改为: {new_level}")


# -------------------------- 主程序入口 --------------------------
if __name__ == "__main__":
    # 自动创建logs文件夹（loguru会自动创建）
    logger.info("=== Loguru 高级示例启动 ===")

    # 执行业务逻辑
    demo_business_logic(10)

    # 执行多线程测试
    logger.info("=== 开始多线程日志测试 ===")
    multi_thread_test()

    # 动态修改日志级别为WARNING（仅输出警告及以上）
    logger.info("=== 动态修改日志级别为 WARNING ===")
    change_log_level("WARNING")

    # 测试级别修改效果
    logger.debug("这条DEBUG日志不会输出")
    logger.warning("这条WARNING日志会输出")

    logger.critical("=== 程序运行结束，关键日志已全部保存 ===")

三、运行结果

C:Users徐鹏Desktop55.venvScriptspython.exe C:Users徐鹏Desktop55main.py 
2026-04-02 09:02:25.883 | 25844 | MainThread | INFO     | __main__::128 - === Loguru 高级示例启动 ===
2026-04-02 09:02:25.884 | 25844 | MainThread | INFO     | __main__:demo_business_logic:83 - 业务逻辑执行中，当前时间: 2026-04-02 09:02:25.884706
2026-04-02 09:02:25.884 | 25844 | MainThread | INFO     | __main__:demo_business_logic:90 - 订单创建成功
2026-04-02 09:02:25.884 | 25844 | MainThread | SUCCESS  | __main__:demo_business_logic:92 - 业务逻辑执行完成✅
2026-04-02 09:02:25.884 | 25844 | MainThread | INFO     | __main__::134 - === 开始多线程日志测试 ===
2026-04-02 09:02:25.885 | 25844 | Thread-0 | INFO     | __main__:demo_business_logic:83 - 业务逻辑执行中，当前时间: 2026-04-02 09:02:25.885793
2026-04-02 09:02:25.885 | 25844 | Thread-1 | INFO     | __main__:demo_business_logic:83 - 业务逻辑执行中，当前时间: 2026-04-02 09:02:25.885793
2026-04-02 09:02:25.885 | 25844 | Thread-0 | INFO     | __main__:demo_business_logic:90 - 订单创建成功
2026-04-02 09:02:25.886 | 25844 | Thread-1 | INFO     | __main__:demo_business_logic:90 - 订单创建成功
2026-04-02 09:02:25.886 | 25844 | Thread-2 | INFO     | __main__:demo_business_logic:83 - 业务逻辑执行中，当前时间: 2026-04-02 09:02:25.886883
2026-04-02 09:02:25.886 | 25844 | Thread-Error | INFO     | __main__:demo_business_logic:83 - 业务逻辑执行中，当前时间: 2026-04-02 09:02:25.886883
2026-04-02 09:02:25.886 | 25844 | Thread-0 | SUCCESS  | __main__:demo_business_logic:92 - 业务逻辑执行完成✅
2026-04-02 09:02:25.886 | 25844 | Thread-1 | SUCCESS  | __main__:demo_business_logic:92 - 业务逻辑执行完成✅
2026-04-02 09:02:25.887 | 25844 | Thread-2 | INFO     | __main__:demo_business_logic:90 - 订单创建成功
2026-04-02 09:02:25.887 | 25844 | Thread-2 | SUCCESS  | __main__:demo_business_logic:92 - 业务逻辑执行完成✅
2026-04-02 09:02:25.887 | 25844 | Thread-Error | ERROR    | __main__:demo_business_logic:95 - 业务逻辑执行失败：
Traceback (most recent call last):

  File "E:Pythonpyhon3.8.2libthreading.py", line 890, in _bootstrap
    self._bootstrap_inner()
    │    └ 
    └ 

  File "E:Pythonpyhon3.8.2libthreading.py", line 932, in _bootstrap_inner
    self.run()
    │    └ 
    └ 

  File "E:Pythonpyhon3.8.2libthreading.py", line 870, in run
    self._target(*self._args, **self._kwargs)
    │    │        │    │        │    └ {}
    │    │        │    │        └ 
    │    │        │    └ (-1,)
    │    │        └ 
    │    └ 
    └ 

> File "C:Users徐鹏Desktop55main.py", line 87, in demo_business_logic
    raise ValueError("数字不能为负数！")

ValueError: 数字不能为负数！
2026-04-02 09:02:25.899 | 25844 | MainThread | INFO     | __main__::138 - === 动态修改日志级别为 WARNING ===
2026-04-02 09:02:25.902 | 25844 | MainThread | WARNING  | __main__::143 - 这条WARNING日志会输出
2026-04-02 09:02:25.902 | 25844 | MainThread | CRITICAL | __main__::145 - === 程序运行结束，关键日志已全部保存 ===

进程已结束，退出代码为 0

总结