---
id: timeloop
version: "1.0.2"
license: MIT
license_treatment: permissive
maintenance: abandoned
---

# timeloop — An elegant way to run period tasks.

License: permissive · Maintenance: abandoned · Downloads: 161.5K/mo

## What it is and what it does

Timeloop is a lightweight scheduler that runs decorated functions at fixed intervals using separate threads. You define jobs with a decorator specifying a timedelta interval, then call start() to begin execution. Each job runs in its own thread, and the service handles graceful shutdown by waiting for all currently executing tasks to finish before stopping.

The package is designed for simple periodic task patterns—background maintenance jobs, polling loops, or recurring checks. It offers two modes: non-blocking (start in a background thread, requiring manual stop() on exit) and blocking (start in the main thread with automatic graceful shutdown on signal). No external dependencies are required, making it a minimal addition to any project.

Use it for:

- Run background maintenance tasks at regular intervals without external job queues.
- Implement polling loops that check an external service at fixed time intervals.
- Schedule periodic health checks or monitoring tasks within a long-running application.
- Execute recurring data synchronization or batch processing jobs on a simple interval schedule.

## Worth the install?

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

Timeloop runs periodic tasks at fixed intervals on separate threads, with graceful shutdown that waits for in-flight jobs to complete.

No. The package is abandoned (last release 2019-02-12, no maintenance since 2022-12-29) and Python support is unspecified, creating risk for compatibility issues with modern Python versions. For new projects, use a maintained alternative. For existing code already using timeloop, migration is low-friction given the simple API, but do not adopt it for new work.

## Install

pip install timeloop
uv add timeloop
poetry add timeloop

## Installing timeloop

Before you install: Installation is frictionless with no runtime dependencies. However, the package is abandoned—last release was 2019-02-12, over 2740 days ago, with no maintenance activity since 2022-12-29. Use only if you accept that no updates or bug fixes will be forthcoming.

License in practice: MIT license is permissive, allowing commercial and private use with minimal restrictions.

Quickstart:

from timeloop import Timeloop
from datetime import timedelta

tl = Timeloop()

@tl.job(interval=timedelta(seconds=2))
def sample_job():
    print("Job executed")

tl.start()
tl.stop()

Python support is unspecified; compatibility with modern Python versions is not documented.

Verify before relying:

- Whether the package works reliably with modern Python versions given unspecified Python support.
- Whether thread-safety guarantees hold under concurrent job execution or high load.
- Whether graceful shutdown actually waits for all in-flight tasks before returning.

## Package facts

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

## Tags

periodic task scheduler, run jobs at intervals, background job runner, threaded task loop, decorator-based scheduling, interval-based job execution, scheduler, abandoned

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