loguru

Loguru replaces the boilerplate of Python’s built-in logging module with a single pre-configured object: from loguru import logger. Instead of wiring up handlers, formatters, and filters separately, one logger.add() call registers a sink — a file path, a stream, a function, or even a coroutine — with its own format, level, filter, colorization, and rotation/retention/compression behavior.

The library folds in features most teams otherwise hand-roll on top of stock logging: automatic file rotation and retention, brace-style string formatting, colorized terminal output, thread- and multiprocess-safe sinks via an optional queue, and an @logger.catch decorator that captures and fully renders exceptions — including local variable values in the traceback — even inside threads where standard logging silently drops them.

Under the hood, _logger.py implements the public Logger/Core classes while dedicated modules handle each concern in isolation: _handler.py manages per-sink dispatch and locking, _file_sink.py handles rotation/retention/compression policy, _colorizer.py and _better_exceptions.py handle terminal color markup and rich traceback rendering respectively, and _string_parsers.py parses human-readable size/time/frequency strings like “500 MB” or “12:00” into rotation rules.

What You Get

• A single pre-configured logger object that writes to stderr out of the box — no boilerplate setup required to start logging
• One add() function to register any sink (file path, stream, function, or coroutine) with its own format, level, filter, and color settings
• Automatic file rotation, retention, and compression driven by simple strings like rotation="500 MB" or retention="10 days"
• An @logger.catch decorator/context manager that captures exceptions — including those raised in threads — and renders full tracebacks with variable values
• Thread-safe sinks by default, with an enqueue=True option for multiprocess-safe and async-safe logging via a background queue
• Structured logging support: bind() and contextualize() attach contextual key/value data to log records, and serialize=True emits JSON

Common Use Cases

• Adding production-ready logging to a script or small application without writing any handler/formatter boilerplate
• Rotating and compressing log files automatically in a long-running service, replacing manual RotatingFileHandler configuration
• Capturing and fully diagnosing exceptions raised inside worker threads or multiprocessing workers that standard logging would otherwise swallow
• Emitting structured, JSON-serialized logs from a library or service for ingestion by a log aggregator
• Adding contextual request/task IDs to log lines across an async or multi-threaded codebase via bind()/contextualize()

Under The Hood

Architecture

Loguru centers on a single pre-instantiated Logger object (loguru/__init__.py) backed by a shared Core that tracks the registered handlers, minimum level, and extra context. Each call to logger.add() constructs a Handler (_handler.py) wrapping a sink object — _simple_sinks.py defines StreamSink, StandardSink, and coroutine/queue-backed variants, while _file_sink.py layers rotation/retention/compression policy on top of file sinks. Formatting and colorization are handled by dedicated _colorizer.py and _better_exceptions.py modules rather than being embedded in the handler, and each Handler owns its own lock (_locks_machinery.py) so sinks are independently thread-safe; multiprocess/async safety is opt-in via an internal queue rather than a global default. This separation — one composable Handler/sink per add() call, coordinated through a shared Core — lets rotation, colorization, and exception rendering evolve independently without touching the public API surface.

Tech Stack

Loguru is pure Python (100% per GitHub’s language breakdown) with almost no runtime dependencies: colorama and win32-setctime are Windows-only extras declared with environment markers in pyproject.toml, and there is no dependency at all on Python’s own logging internals beyond an optional standard-library interception bridge (_simple_sinks.py’s StandardSink). The project builds with Flit (flit_core backend), supports Python 3.5 through 3.14 plus PyPy per its classifiers, and ships a py.typed marker with a separate __init__.pyi stub (kept apart from the implementation because type checkers can’t merge stubs with dynamically constructed objects like the module-level logger instance).

Code Quality

The tests/ directory contains over 50 targeted test modules (e.g. test_filesink_rotation.py, test_exceptions_catch.py, test_multiprocessing.py, test_coroutine_sink.py) run under pytest with pytest-cov for coverage and freezegun for deterministic datetime tests, plus a typesafety/ subdirectory for type-stub verification. Linting runs through Ruff with an extensive rule set (F, E, W, I, B, N, D, PT, PYI, RET, RUF) and numpydoc-style docstring conventions, Black for formatting, and Mypy pinned per Python version for type checking. CI (GitHub Actions) runs a dedicated tests.yml, lint.yml, docs.yml, and a CodeQL security scan on every push and PR, and the project is configured to treat warnings as test failures by default (filterwarnings = ['error']) with explicit, justified exceptions.

What Makes It Unique

Loguru’s core differentiator is collapsing standard logging’s Logger/Handler/Formatter/Filter object graph into a single logger.add() call per sink, removing the setup step that causes many Python projects to reach for print() instead of logging. Its exception handling goes further than typical logging libraries by rendering full tracebacks with the actual values of local variables at each frame (via a better_exceptions-derived renderer) and by correctly propagating exceptions raised inside threads, which standard logging does not surface at all. Human-readable rotation/retention strings ("500 MB", "12:00", "1 week") parsed by a dedicated string-parsing module, combined with built-in async/multiprocess-safe sinks via an opt-in queue, cover operational concerns that most other logging libraries leave to external configuration or third-party handlers.