coloredlogs

coloredlogs enables colored terminal output for Python’s standard logging module without requiring you to replace your existing logging setup. Its ColoredFormatter subclasses logging.Formatter and injects ANSI escape sequences into log records, so a single coloredlogs.install() call — mirroring the familiar logging.basicConfig() signature — is enough to get readable, color-coded log levels in any UNIX terminal or modern Windows console.

Beyond basic colorization, the package includes environment-variable-driven configuration (log format, date format, level styles, field styles), a syslog helper module for UNIX system logging, an ANSI-to-HTML converter for emailing colored cron output, and custom log fields like %(hostname)s, %(programname)s, and %(username)s. It gracefully falls back to colorama on older Windows versions and disables color automatically when output isn’t attached to an interactive terminal.

What You Get

• A ColoredFormatter that colorizes log level names and messages using only the standard 8-color ANSI palette for broad terminal compatibility
• A one-line coloredlogs.install() API that mirrors logging.basicConfig(), installable on the root logger or any specific logger instance
• Environment-variable configuration for log format, date format, and per-level/per-field color styles (COLOREDLOGS_LOG_FORMAT, COLOREDLOGS_LEVEL_STYLES, etc.) with no code changes required
• Custom logging.Filter subclasses that populate %(hostname)s, %(programname)s, and %(username)s fields automatically when referenced in a format string
• A coloredlogs.syslog module (enable_system_logging()) for easy UNIX syslog integration alongside colored terminal output
• An ANSI-to-HTML converter and ColoredCronMailer context manager so cron job output emails render colors instead of raw escape codes
• Automatic native ANSI support detection on modern Windows 10, with a colorama fallback for older Windows versions

Common Use Cases

• Adding readable, color-coded log output to a CLI tool or script during local development without touching existing logging.getLogger() calls
• Standardizing colored, leveled log output across a small service or automation script that previously used logging.basicConfig()
• Emailing colorized cron job output as HTML via ColoredCronMailer so scheduled task failures are easy to scan in an inbox
• Forwarding application logs to syslog on a UNIX server while retaining colored console output for interactive debugging

Under The Hood

Architecture: The package centers on a single-module design: coloredlogs/init.py (roughly 1,500 lines) defines the public API (install(), increase_verbosity(), find_hostname(), etc.), the ColoredFormatter class (subclassing a BasicFormatter which itself subclasses logging.Formatter), and supporting logging.Filter subclasses (HostNameFilter, ProgramNameFilter, UserNameFilter) that populate custom format fields. Two focused submodules extend this core: coloredlogs/syslog.py wraps logging.handlers.SysLogHandler for UNIX system logging, and coloredlogs/converter/ implements an ANSI-escape-sequence-to-HTML converter used by the cron-mailing feature. A small cli.py exposes a coloredlogs --demo console script for visually verifying color output. The design deliberately avoids introducing new logging concepts — it augments the standard library’s Formatter/Filter/Handler classes rather than replacing them, which keeps integration with existing code trivial.

Tech Stack: Pure Python (97% of the codebase), supporting Python 2.7 and 3.5+ plus PyPy, reflecting the project’s long lifespan (created 2013). Its only runtime dependency is humanfriendly (the same author’s companion package), used for terminal capability detection, ANSI style helpers, and boolean/text coercion utilities. The optional cron extra pulls in capturer>=2.4 for output capturing during HTML-mailed cron jobs, and colorama is used as a fallback on legacy Windows. Packaging uses a classic setuptools setup.py (distutils-based, predating pyproject.toml conventions) with Travis CI and Coveralls badges indicating its CI history.

Code Quality: The package ships a substantial dedicated test suite (coloredlogs/tests.py, ~30KB) covering the formatter, filters, verbosity helpers, and CLI, built on the author’s humanfriendly.testing utilities (PatchedAttribute, PatchedItem, retry) for deterministic environment-dependent testing. Docstrings are thorough and Sphinx-formatted throughout init.py, doubling as the published API reference. Code style favors small, single-purpose functions (find_hostname, find_program_name, find_username) with clear naming, though the reliance on distutils and support for Python 2.7 signals an older, stable-but-aging codebase rather than one following current packaging conventions.

API Design: The core entry point, coloredlogs.install(level=‘DEBUG’), is deliberately designed as a near drop-in replacement for logging.basicConfig(), minimizing the learning curve for anyone already familiar with the standard library. Configuration can happen entirely through environment variables (COLOREDLOGS_LOG_FORMAT, COLOREDLOGS_LEVEL_STYLES, etc.) without touching application code, which is convenient for ops-style deployments. The library also respects the $NO_COLOR convention and auto-detects non-interactive output, so it does the right thing by default with minimal boilerplate required to get started.