---
id: pygelf
version: "0.4.3"
license: MIT
license_treatment: permissive
maintenance: aging
---

# pygelf — Logging handlers with GELF support

License: permissive · Maintenance: aging · Downloads: 388.3K/mo

## What it is and what it does

pygelf is a Python logging library that bridges the standard logging module to Graylog servers by providing handlers that format and transmit logs in GELF format. It supports five transport protocols—TCP, UDP, TLS (encrypted TCP), HTTP, and HTTPS—allowing you to choose based on your network and security requirements. The library handles the GELF message structure automatically, including mandatory fields like version, timestamp, syslog-compliant log level, hostname, and optional stack traces for exceptions.

You integrate it by adding one or more handlers to your logger, specifying the target server's host and port. The package supports optional features like debug mode (which adds file, line, module, and function metadata), static and dynamic custom fields, environment variable injection, message compression, and TLS certificate validation. It has no external runtime dependencies, making it lightweight to add to existing Python projects.

Use it for:

- Centralize logs from a Python application to a Graylog instance for aggregated monitoring and analysis.
- Send application logs over encrypted TLS to a remote Graylog server in a secure network environment.
- Add structured metadata (app name, request ID, user context) to each log entry for better searchability in Graylog.
- Route exception stack traces and debug information to Graylog for post-mortem analysis.
- Integrate logging into a Flask or Django application configuration file to send logs via HTTP to Graylog.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Provides Python logging handlers that send log messages to Graylog servers using the GELF (Graylog Extended Log Format) protocol over TCP, UDP, TLS, HTTP, or HTTPS.

Yes, if you are already using Graylog and need Python logging integration. The package is stable, has no dependencies, and supports modern Python versions. However, maintenance is aging (last release 426 days ago), so verify that it works with your specific Graylog version and Python release before committing to production. No known security vulnerabilities.

## Install

pip install pygelf
uv add pygelf
poetry add pygelf

## Installing pygelf

Before you install: Low friction to install; no runtime dependencies. Maintenance is aging—last release was 426 days ago, though the repository remains active with a recent commit on 2025-06-25 and modest community engagement (85 stars).

License in practice: MIT license is permissive, allowing use in commercial and proprietary projects with minimal restrictions beyond attribution.

Quickstart:

pip install pygelf

from pygelf import GelfTcpHandler
import logging

logger = logging.getLogger()
logger.addHandler(GelfTcpHandler(host='127.0.0.1', port=9401))
logger.info('hello gelf')

Requires a running GELF-compatible server (e.g., Graylog) listening on the specified host and port.

Verify before relying:

- Whether the package works reliably with Python 3.13 or if 3.13 support is merely declared but untested.
- Current state of PyPy compatibility given the aging maintenance status.

## Package facts

- License: MIT (permissive)
- Python support: unspecified
- Install friction: low
- Maintenance: aging
- Downloads: 388.3K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

graylog logging handler, gelf protocol python, send logs to graylog, python gelf client, graylog extended log format, centralized logging graylog, tcp udp logging handler, graylog-integration, structured-logging

[View on SkillFed](https://skillfed.io/packages/pygelf) · [View on PyPI](https://pypi.org/project/pygelf/)