concurrent-log-handler

What it is and what it does

concurrent-log-handler extends Python's standard logging module with handlers that safely coordinate writes from multiple processes and threads to a single log file. It uses file locking (via portalocker) to serialize access and prevent corruption when concurrent writers attempt to log simultaneously. The package supports both size-based rotation (e.g., rotate after 512 KB) and time-based rotation (e.g., daily), with optional gzip compression of rotated files.

The package is designed for applications running in multiple processes on the same machine or across different machines sharing a network drive, where a centralized log file is required without the overhead of external logging services. Version 0.9.29 addresses race conditions in forked child processes and logging during interpreter shutdown. Each process must create its own handler instance; handlers cannot be pickled and reused across process boundaries, though threads within a single process can safely share one handler.

Use it for:

• Multi-worker web applications (e.g., Gunicorn, uWSGI) logging to a shared file on the same or networked filesystem.
• Batch processing jobs spawned via multiprocessing that need centralized audit or error logs.
• Long-running services with periodic log rotation to manage disk space without external log management.
• Development and testing environments where multiple test processes write to a single consolidated log.
• Applications on Windows and POSIX systems requiring cross-platform file locking without external dependencies.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Provides thread-safe and process-safe logging handlers for Python's standard logging module, enabling multiple processes to write concurrently to a single log file with built-in size-based and time-based rotation.

Yes. The package is actively maintained, has no known vulnerabilities, low install friction, and solves a real problem in multi-process Python applications. Use it when you need safe concurrent logging to a single file with rotation. Not necessary if you're using a centralized logging service (e.g., CloudWatch, Logstash) or a single-process application.

Install

concurrent-log-handler on PyPI

pip install concurrent-log-handler

uv add concurrent-log-handler

poetry add concurrent-log-handler

Installing concurrent-log-handler

Before you install

Low friction: pure Python wheel with a single runtime dependency (portalocker >= 2.6.0). Actively maintained as of February 2026, with recent fixes for fork-related race conditions and logging during shutdown. No known vulnerabilities.

License in practice

Apache-2.0 (permissive): you may use, modify, and distribute this package freely in commercial and open-source projects, provided you include a copy of the license and note any modifications.

Quickstart

import logging
from concurrent_log_handler import ConcurrentRotatingFileHandler

logger = logging.getLogger(__name__)
handler = ConcurrentRotatingFileHandler(
    "mylogfile.log", "a", maxBytes=512*1024, backupCount=5
)
logger.addHandler(handler)
logger.info("Concurrent log message")

Each process must instantiate its own handler; handlers cannot be serialized and shared across process boundaries (including forked children). Threads within the same process can share a single instance.

Verify before relying

• Whether portalocker >= 2.6.0 introduces any breaking changes or new dependencies beyond pywin32 on Windows.
• Performance characteristics under high-throughput logging scenarios relative to other concurrent logging solutions.
• Behavior when log files are on network drives with high latency or intermittent connectivity.

Package facts

Evidence: concurrent_log_handler-0.9.29-py3-none-any.whl

Keywords: QueueHandler, QueueListener, linux, logging, portalocker, rotate, unix, windows

Tags

More Python Modules packages