crontab-win

A simple cron-like task scheduler for Windows.

This tool allows you to schedule tasks using a crontab.txt file, similar to how cron works on Unix-like systems.

For background on the project read this blogpost about it

Installation

Install this tool using pip:

pip install crontab-win

Usage

This package provides two commands: crontab and ctab. Both can be used interchangeably.

Running the Scheduler

To start the scheduler, simply run:

crontab

or

ctab

This will start the scheduler in the foreground. It will read your crontab file and execute tasks as per the schedule. You should keep this window minimized.

By default, the scheduler looks for a file named crontab.txt in your user's home directory (e.g., C:\Users\YourUser\crontab.txt).

You can specify a different crontab file using the -c or --crontab-file option:

crontab -c "C:\path\to\my\custom_crontab.txt"

Editing the Crontab File

To open your crontab file for editing, use the show command:

crontab show

or

ctab show

This will open crontab.txt in your default text editor. If the file doesn't exist, it will be created with a helpful guide.

Crontab Syntax

Each line in the crontab file represents a single task. The syntax is as follows:

┌───────────── minute (0 - 59)
│ ┌───────────── hour (0 - 23)
│ │ ┌───────────── day of the month (1 - 31)
│ │ │ ┌───────────── month (1 - 12 or JAN-DEC)
│ │ │ │ ┌───────────── day of the week (0 - 6 or SUN-SAT)
│ │ │ │ │
│ │ │ │ │
* * * * * command to execute

You can use * for any value, or provide specific numbers. Ranges (2-5) and lists (2,5) are also supported.

Special Nicknames

For convenience, you can use the following special nicknames instead of the five-field time specification:

Examples

Here are some example crontab entries:

# Run a script every 15 minutes
*/15 * * * * python C:\Users\MyUser\scripts\my_script.py

# Run a backup at 5 a.m. every day
0 5 * * * tar -zcf /var/backups/home.tgz /home/

# Use a special nickname to run a task hourly
@hourly echo "This runs every hour" >> C:\temp\hourly.log

# Run a task on the first day of every month
0 0 1 * * echo "Monthly report generation"

# Run a task every Monday at 8:00 AM
0 8 * * MON python C:\path\to\your\script.py

Start Crontab at Startup

To run the crontab scheduler automatically when Windows starts, you can create a simple batch file.

1. Create a new file named crontab_startup.bat.

2. Add the following content to the file:

   @echo off
   start /min ctab
   

3. Place this batch file in your startup folder. You can open the startup folder by pressing Win + R, typing shell:startup, and pressing Enter.

Development

To contribute to this tool, first check out the code. Then create a new virtual environment:

cd crontab-win
python -m venv venv
source venv/bin/activate

Now install the dependencies and test dependencies:

pip install -e '.[test]'

To run the tests:

python -m pytest