Python Crontab API

3.3.0 · active · verified Thu Apr 09

python-crontab provides a Pythonic API to create, manage, read, and write crontab entries and entire crontab files, including user-specific and system-wide crontabs. As of version 3.3.0, it offers a unified `CronTab` class for all crontab manipulations, simplifying interaction with cron jobs from Python. The library is actively maintained with an irregular release cadence.

Warnings

breaking Version 3.0.0 introduced significant breaking changes. The `Crontab` (system-wide) and `CrontabEntry` classes were removed/renamed. All crontab manipulations now happen through the unified `CronTab` class, with parameters like `user` or `tabfile` to specify the target crontab.
Fix: Migrate code to use `from crontab import CronTab` and adjust constructor arguments (e.g., `CronTab(user=True)`, `CronTab(user='root')`, `CronTab(tabfile='/etc/crontab')`). `CrontabEntry` objects are now `CronItem` objects within `CronTab` instances.
gotcha Changes made to the `CronTab` object are not persisted to the actual crontab file until the `.write()` method is explicitly called. Forgetting to call `.write()` will result in no actual changes to the system's cron jobs.
Fix: Always ensure `my_cron.write()` is called after making any additions, modifications, or removals of cron jobs to persist the changes.
gotcha Running `python-crontab` to modify system or other user's crontabs often requires elevated privileges (e.g., `sudo`). Without proper permissions, operations like `my_cron.write()` might fail silently or raise permission errors.
Fix: Run your Python script with `sudo` if you intend to modify crontabs other than the current user's default. Be cautious when granting elevated privileges.
gotcha When finding jobs, methods like `find_command`, `find_comment`, or iteration (`for job in my_cron:`) return `CronItem` objects. Modifying these `CronItem` objects directly requires `my_cron.write()` to save the changes.
Fix: After modifying any attributes of a `CronItem` obtained from `my_cron`, ensure `my_cron.write()` is called to apply the changes.

Install

pip install python-crontab Install stable version

Imports

CronTab
```
from crontab import CronTab
```
The top-level module is `crontab`, not `python_crontab` matching the package name.
CronTab
```
from crontab import CronTab
```
The main class is `CronTab` (capital 'T'), not `Crontab` (lowercase 't'), especially since version 3.0.0.

Quickstart

This example initializes a crontab for the current user, adds a new job to run every minute, and then persists the changes to the user's crontab file. Remember that `write()` is crucial to save modifications. This requires the Python script to have appropriate permissions to modify the crontab.

from crontab import CronTab

# Initialize crontab for the current user. Permissions might be needed.
# For system-wide crontabs, use CronTab(user='root') and ensure proper permissions.
my_cron = CronTab(user=True)

# Create a new cron job
job = my_cron.new(command='echo "Hello from cron!" >> /tmp/cron_test.log', comment='my_test_job')
job.minute().every(1) # Run every minute

# Iterate existing jobs (optional)
print('Existing jobs:')
for j in my_cron:
    print(j)

# IMPORTANT: Write changes to the crontab file
my_cron.write()
print('Crontab updated. Check /tmp/cron_test.log in a minute.')

# To remove a job later (example):
# for job_to_remove in my_cron.find_comment('my_test_job'):
#     my_cron.remove(job_to_remove)
# my_cron.write()

view raw JSON →