napcron

napcron is a small, Python-based, parallel replacement for anacron. It ensures periodic jobs (hourly, daily, weekly, monthly, etc.) still run even if the system was powered off, suspended, or offline when they were scheduled.

Unlike cron, it records when tasks last succeeded and executes only those that are due. Unlike anacron, it is easy to configure.

Installation

pip install napcron

Usage

napcron is designed to be executed once per hour via cron, systemd, or any scheduler. It reads a YAML configuration file, checks which tasks are due, evaluates their requirements, and executes them in parallel.

Cron job example

Edit your user crontab (crontab -e):

@hourly napcron  # uses ~/.napcron.yaml by default

Configuration

The default config file lives at ~/.napcron.yaml; if it doesn't exist yet, running napcron once will create it.

From there you can extend it. Example `/home/user/.napcron.yaml`:

```yaml
hourly:
  - /usr/local/bin/refresh-cache.sh

daily:
  - bash /home/user/a.sh:
      - internet
  - python $HOME/a.py: internet
  - ~/just_run_me.sh

weekly:
  - /cleanup_logs.sh: [internet, ac_power, rerun_onfail]

monthly:
  - python ~/rotate_backups.py

Explanation

Features

• Runs missed periodic jobs (hourly, daily, weekly, monthly)

• Executes due tasks in parallel

• Supports configurable requirements:

  • internet – verify network connectivity
  • ac_power – ensure external power is connected
  • battery – only runs when on battery
  • rerun_onfail – retry failed jobs immediately instead of waiting for the next interval

• Simple YAML configuration

• Persistent state tracking in ~/.local/state/napcron/

• Atomic file lock to prevent overlapping runs

• Safe dry-run mode (--dry-run)

Requirements

Each task may specify one or more requirements that must be met before execution. napcron provides the following built-in checks:

Custom requirement checks can easily be added by extending the REQUIREMENTS dictionary in napcron.py.

Example:

def req_gpu_available(cmd: str) -> bool:
    return shutil.which("nvidia-smi") is not None

REQUIREMENTS["gpu"] = req_gpu_available

Used in YAML:

daily:
  - python train.py: gpu
  - python flaky.py:
      - rerun_onfail

Command-line Options

State Management

napcron stores metadata about executed tasks in JSON format at:

~/.local/state/napcron/<config-name>.state.json

Each entry includes information such as last success, last attempt, and last exit code.

Example:

{
  "tasks": {
    "daily::bash /home/daniel/a.sh": {
      "frequency": "daily",
      "cmd": "bash /home/daniel/a.sh",
      "last_success": "2025-10-26T10:00:00+00:00",
      "last_status": 0
    }
  }
}