Loguru - Python Logging Made Simple

Loguru - Python Logging Made Simple

Research Date: 2026-02-09 Website: https://loguru.readthedocs.io GitHub: https://github.com/Delgan/loguru PyPI: https://pypi.org/project/loguru/ Version: 0.7.3 License: MIT Primary Language: Python (100%)

Overview

Loguru is a drop-in replacement for Python's standard logging module that eliminates boilerplate configuration. It provides a single pre-configured global logger object that outputs to stderr by default and can be fully reconfigured with a single add() call. Zero required dependencies on Linux/macOS (only colorama on Windows).

Problem Addressed

Key Statistics

Key Features

Zero-Config Global Logger

from loguru import logger
logger.debug("Works immediately, outputs to stderr")

Single logger instance, no getLogger() needed. Pre-configured with colored stderr output.

Unified add() Function

Replaces Handler + Formatter + Filter with one call. Sinks can be:

• File-like objects (sys.stderr)
• File paths (string/Path, with automatic file management)
• Callables (any function accepting a message)
• Coroutine functions (async sinks)
• stdlib logging.Handler instances

logger.add("app.log", rotation="500 MB", retention="10 days", compression="gz")
logger.add(sys.stdout, format="{time} {level} {message}", level="INFO")
logger.add(custom_sink_function, serialize=True)

Seven Built-in Log Levels

Custom levels via logger.level("AGENT_STEP", no=25).

Exception Catching

@logger.catch(default=None)
def risky(a, b):
    return a / b

result = risky(10, 0)  # Returns None, error logged with full traceback

with logger.catch(message="Something failed"):
    do_risky_operation()

Structured Logging and Context

# bind() - returns new logger with extra context
child = logger.bind(request_id="abc-123", user="admin")
child.info("Processing")

# contextualize() - context-local via contextvars (thread/async safe)
with logger.contextualize(task_id=42):
    logger.info("In context")  # extra = {'task_id': 42}

# serialize=True - JSON output
logger.add(sink, serialize=True)

# patch() - modify record dict dynamically
logger = logger.patch(lambda r: r["extra"].update(version="1.0"))

Lazy Evaluation

logger.opt(lazy=True).debug("Result: {x}", x=lambda: expensive_computation())

Lambda is never called if sink level is above DEBUG.

Per-Message Configuration via opt()

logger.opt(exception=True).info("Log with traceback")
logger.opt(colors=True).info("<blue>colored</blue> message")
logger.opt(record=True).info("Line: {record[line]}")
logger.opt(raw=True).info("Bypass formatting\n")
logger.opt(depth=1).info("Use parent stack frame")

File Rotation, Retention, and Compression

logger.add("app.log", rotation="500 MB")      # Size-based
logger.add("app.log", rotation="12:00")        # Time-based (daily at noon)
logger.add("app.log", rotation="1 week")       # Duration-based
logger.add("app.log", retention="10 days")     # Auto-cleanup old files
logger.add("app.log", compression="gz")        # Compress on rotation

stdlib Compatibility

Three integration patterns:

1. stdlib Handler as Loguru sink: logger.add(syslog_handler)
2. Propagate Loguru to stdlib: Custom PropagateHandler
3. Intercept stdlib into Loguru: InterceptHandler pattern funnels all stdlib logging through Loguru

Library-Friendly disable/enable

# In library code:
logger.disable("my_library")   # All logging becomes no-op
# In application code:
logger.enable("my_library")    # Re-enable

Environment Variable Configuration

Default stderr handler configurable via: LOGURU_FORMAT, LOGURU_LEVEL, LOGURU_DIAGNOSE, LOGURU_BACKTRACE, LOGURU_COLORIZE, LOGURU_SERIALIZE, LOGURU_ENQUEUE, LOGURU_CATCH. Also supports NO_COLOR and FORCE_COLOR.

Multiprocess-Safe Enqueue

logger.add("file.log", enqueue=True)   # Messages via multiprocessing-safe queue
await logger.complete()                  # Wait for all enqueued messages

Technical Architecture

Package Structure

Pure Python package (~200KB, 21 files). No compiled extensions.

Architecture Pattern

Single-instance, handler-dispatch model. Logger maintains an internal list of handlers. add() creates handlers with specified sink/format/filter/level. Log methods dispatch to all handlers passing level and filter checks. bind(), contextualize(), patch(), opt() return lightweight wrapper instances that modify the record without creating separate loggers.

Rich Record Dict

Every log message carries a record dict:

Installation and Usage

# pip
pip install loguru

# uv
uv pip install loguru
uv add loguru

# PEP 723 inline script metadata
# /// script
# dependencies = ["loguru"]
# ///

Quick Start

from loguru import logger

# Remove default handler, add custom one
logger.remove()
logger.add("app.log", rotation="10 MB", retention="7 days", compression="gz")
logger.add(sys.stderr, level="WARNING", colorize=True)

# Log with context
with logger.contextualize(request_id="abc-123"):
    logger.info("Processing request")

# Catch exceptions
@logger.catch
def main():
    process_data()

InterceptHandler Pattern (Unify All Logging)

import logging
import inspect

class InterceptHandler(logging.Handler):
    def emit(self, record):
        try:
            level = logger.level(record.levelname).name
        except ValueError:
            level = record.levelno
        frame, depth = inspect.currentframe(), 0
        while frame:
            filename = frame.f_code.co_filename
            if depth > 0 and not (filename == logging.__file__ or
                ("importlib" in filename and "_bootstrap" in filename)):
                break
            frame = frame.f_back
            depth += 1
        logger.opt(depth=depth, exception=record.exc_info).log(level, record.getMessage())

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

Relevance to Claude Code Development

Applications

1. CLI Tool Logging: Loguru's default stderr output avoids interfering with stdout piping. Environment variable control (LOGURU_LEVEL=DEBUG) enables verbose mode without code changes. NO_COLOR support follows CLI conventions.

2. Agent Script Diagnostics: Python scripts in plugins/**/scripts/ that use PEP 723 can add loguru as a dependency for structured diagnostic output. The bind() method enables per-task context (agent name, step number) in log output.

3. Exception Handling in Hooks: @logger.catch wrapping hook entry points provides automatic error logging with full variable-value tracebacks, replacing silent failures.

4. Unified Library Logging: The InterceptHandler pattern funnels all stdlib logging from third-party libraries (httpx, requests, etc.) through Loguru for consistent formatting and filtering.

Patterns Worth Adopting

1. contextualize() for Request Tracking: Agents processing multiple tasks can attach task_id, agent_name, model to all log messages within an async context using contextvars.

2. serialize=True for Machine-Readable Logs: JSON-structured logs with the full record dict enable downstream log analysis and monitoring.

3. Lazy Evaluation for Debug Logging: Expensive debug output (serializing large model inputs) can use opt(lazy=True) to avoid computation when debug is disabled.

4. disable()/enable() for Library Code: Libraries/plugins can disable their Loguru logging by default, letting the consuming application opt in.

Integration Opportunities

1. Drop-in for print() Debugging: Scripts currently using print() for diagnostics can switch to logger.debug() with zero configuration overhead.

2. File Logging for Long-Running Scripts: Scripts that run data processing or sync operations benefit from built-in rotation/retention/compression without external log management.

3. Structured Context in Multi-Agent Workflows: bind(agent="curator", step="fetch") enables filtering and searching logs across concurrent agent executions.

Considerations

1. Not stdlib: Adding Loguru as a dependency means scripts are no longer stdlib-only. For PEP 723 scripts this is fine; for scripts targeting minimal environments, stdlib logging may be preferred.

2. Global State: The single logger instance means add()/remove() calls affect all code using Loguru in the process. This is usually fine for scripts but requires care in library code.

3. diagnose=True Security: Variable values in tracebacks can leak secrets. Should be set to False in production or when logging to persistent sinks.

References

1. Loguru Documentation - https://loguru.readthedocs.io (accessed 2026-02-09)
2. Loguru GitHub Repository - https://github.com/Delgan/loguru (accessed 2026-02-09)
3. Loguru README - https://raw.githubusercontent.com/Delgan/loguru/master/README.md (accessed 2026-02-09, via research agent)
4. GitHub API - Repository Metadata - https://api.github.com/repos/Delgan/loguru (accessed 2026-02-09): stars, forks, license, creation date
5. GitHub API - Latest Release - https://api.github.com/repos/Delgan/loguru/releases/latest (accessed 2026-02-09): v0.7.3, release notes
6. Installed Package Metadata - importlib.metadata.metadata('loguru') on loguru 0.7.3: version, license, Python requirement, dependencies
7. Installed Package Source - /usr/local/lib/python3.11/dist-packages/loguru/: file sizes, architecture, type stubs verified by direct inspection
8. Installed Package Help - help(logger.add), help(logger.catch), help(logger.opt), help(logger.bind), help(logger.contextualize): parameter documentation and signatures verified by direct execution

Freshness Tracking

Update Triggers

• New major/minor release beyond 0.7.x
• Growth beyond 25,000 stars
• Addition of async-native features or major API changes
• Python version support changes (currently >=3.5)
• Changes to dependency model (currently zero deps on Linux/macOS)