python-crontab

library3.3.0pypypi✓ verified 27d ago

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.

workflow devops

pip install python-crontab

package ↗homepage ↗

INSTALL

IMPORT

SIG · PYTHON-CRONTAB

python-crontab

workflowpythonv3.3.0

Install

1.6s avg

Import

51ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.3.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.052s · 17.9MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.050s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

CronTab

✓ from crontab import CronTab

✗ from python_crontab import CronTab

The top-level module is `crontab`, not `python_crontab` matching the package name.

CronTab

✓ from crontab import CronTab

✗ from crontab import Crontab

The main class is `CronTab` (capital 'T'), not `Crontab` (lowercase 't'), especially since version 3.0.0.

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()

crontab --version

Debug

Known issues

breakingVersion 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.

affects: >=3.0.0

gotchaChanges 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.

affects: All

gotchaRunning `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.

affects: All

gotchaWhen 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.

affects: All

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'crontab'

The `python-crontab` package, which provides the `crontab` module, is not installed in the active Python environment.

fix

pip install python-crontab

AttributeError: 'CronTab' object has no attribute 'jobs'

The `CronTab` object is directly iterable to access its jobs; it does not expose a public attribute named `jobs` (or `entries`) for this purpose.

fix

Iterate directly over the CronTab object: `for job in my_crontab:` or convert to a list: `list_of_jobs = list(my_crontab)`.

OSError: [Errno 13] Permission denied: '/var/spool/cron/username'

The Python script is attempting to write to a crontab file (e.g., another user's crontab or the system crontab) without the necessary operating system permissions.

fix

Run the script with appropriate elevated privileges (e.g., `sudo python your_script.py`) or ensure you have write access to the target crontab file.

TypeError: CronTab.__init__() got an unexpected keyword argument 'tab'

The `CronTab` constructor expects `tabfile` as the keyword argument to specify the path to a crontab file, not `tab`.

fix

Use `tabfile` instead of `tab` when initializing `CronTab`: `my_crontab = CronTab(tabfile='/path/to/crontab')`

Upgrade

Version history

3.3.0latest on PyPI · released Jul 13, 2025

Audit

Dependencies

No dependency data recorded yet.

Agent activity

25 hits · last 30 days

node

OpenAI (training)

Resources

packagehttps://pypi.org/project/python-crontab/ ↗

homepagehttps://gitlab.com/doctormo/python-crontab/ ↗