---
id: pygtail
version: "0.14.0"
license: GPL v2
license_treatment: copyleft
maintenance: aging
---

# pygtail — Reads log file lines that have not been read.

License: copyleft · Maintenance: aging · Downloads: 225.5K/mo

## What it is and what it does

Pygtail is a Python port of logcheck's logtail2 utility. It maintains an offset file to track which lines of a log file have already been read, then returns only the new lines on subsequent calls. It handles log rotation transparently, supporting both copytruncate-style rotation (where the file is copied then truncated) and inode-based rotation (where the file is moved and a new one created).

The package works both as a command-line tool and as a Python library. From the CLI, you point it at a log file and it prints unread lines; in code, you instantiate a Pygtail object and iterate over lines. It offers fine-grained control over when the offset is written back to disk, custom log rotation patterns, and options to read from the end of large files if the offset file is missing.

Use it for:

- Monitor application logs in real time by reading only new entries since the last check, avoiding re-processing old lines.
- Build log aggregation pipelines that track which lines have been shipped to a central system, using the offset file as a checkpoint.
- Process rotated logs without losing track of position across rotation boundaries, especially in high-volume logging scenarios.
- Implement custom log watchers that need fine-grained control over when offset state is persisted to disk.

## Worth the install?

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

Pygtail reads only the new lines from a log file since the last read, tracking position with an offset file and handling log rotation automatically.

Yes, if you need incremental log reading with rotation support and can accept a copyleft license. The package is stable and has no known vulnerabilities, but maintenance is stalled since 2022; verify compatibility with your Python version and log rotation setup before relying on it for production use.

## Install

pip install pygtail
uv add pygtail
poetry add pygtail

## Installing pygtail

Before you install: Low install friction with no runtime dependencies. Maintenance is aging—last release was 2022-11-06 and the repository shows no recent activity, though it remains unarchived with a final commit in 2025-09-04.

License in practice: Licensed under GPL v2 (copyleft). Any code that imports and uses pygtail must also be distributed under a compatible copyleft license; proprietary or permissive-licensed projects may face licensing conflicts.

Quickstart:

from pygtail import Pygtail

for line in Pygtail("some.log"):
    print(line, end='')

Verify before relying:

- Whether the package works reliably with modern Python versions beyond those listed in classifiers (2.6, 2.7, 3.x unspecified).
- Current compatibility with contemporary log rotation schemes and whether the copytruncate and inode-based rotation modes remain effective.

## Package facts

- License: GPL v2 (copyleft)
- Python support: unspecified
- Install friction: low
- Maintenance: aging
- Downloads: 225.5K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

tail log file new lines, log file offset tracking, log rotation handling, read unread log lines, logtail python port, incremental log reading, log-tailing, offset-tracking

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