Skip to main content

Tiny date, time diff calculator with timers

Project description


Latest release AUR PyPI Debian Buster+ Fedora 27+ Ubuntu Bionic+

Availability License Build Status


pdd (Python3 Date Diff) is a small cmdline utility to calculate date and time difference. It can also be used as a timer. If no program arguments are specified it shows the current date, time and timezone.

There are utilities and shell scripts which do what pdd does. However, pdd has been written with only one goal - simplicity. Users shouldn't have memorize anything.

Love smart and efficient utilities? Explore my repositories. Buy me a cup of coffee if they help you.

Donate via PayPal!

Table of Contents


  • easy to use, minimal dependencies
  • calculate date and time difference
  • calculate diff from today and now
  • add, subtract duration (timeslice) to/from date (time)
  • countdown timer with command piggybacking
  • custom resolution stopwatch
  • non-verbose mode for background timers
  • show current date, time and timezone



pdd requires Python 3.5 (or later) and the dateutil module.

To install dateutil on Ubuntu, run:

$ sudo apt-get install python3-dateutil

or, using pip3:

$ sudo pip3 install python-dateutil

From a package manager

Release packages

Packages for Arch Linux, CentOS, Debian, Fedora and Ubuntu are available with the latest stable release.

From source

If you have git installed, clone this repository. Otherwise download the latest latest stable release or development version (risky).

Install to default location (/usr/local):

$ sudo make install

To remove, run:

$ sudo make uninstall

PREFIX is supported, in case you want to install to a different location.

Running standalone

pdd is a standalone utility. From the containing directory, run:

$ chmod +x pdd
$ ./pdd


cmdline options

usage: pdd [-h] [-d yyyy mmm dd [yyyy mmm dd | y m d]]
           [-t hh:mm:ss [hh:mm:ss | h:m:s]] [--add] [--sub]
           [--day yyyy mmm dd] [-c hh:mm:ss] [-r command] [-s [resolution]]
           [keywords [keywords ...]]

Tiny date, time difference calculator with timers.

positional arguments:
  keywords              diff/add/subtract from today or now

optional arguments:
  -h, --help            show this help message and exit
  -d yyyy mmm dd [yyyy mmm dd | y m d]
                        calculate date difference
  -t hh:mm:ss [hh:mm:ss | h:m:s]
                        calculate time difference
  --add                 add to date (/today) or time (/now)
  --sub                 subtract from date (/today) or time (/now)
  --day yyyy mmm dd     show day of the week on a date
  -c hh:mm:ss           start a countdown timer
  -r command            run command when countdown timer reaches 0
  -s [resolution]       start a stopwatch [default resolution: 3 (ms)]
  -q                    quiet mode for background timer/stopwatch

Operational notes

  • ISO 8601 format. Month can be specified as month number (e.g. Jan - 1, Dec - 12).
  • Time is in 24-hr format.
  • The absolute difference is shown. Argument order is ignored.
  • The end date is excluded in date difference calculations.
  • Hour, minute or second can be omitted. Partial inputs are recognized as mm:ss or ss.
  • The keybind to stop timers is Ctrl-C.


  1. Calculate diff from today:

    $ pdd 2014 Jan 15
  2. Calculate diff from now:

    $ pdd 24:00:00
    $ pdd 0
  3. Calculate date diff:

    $ pdd -d 1983 jul 3 2014 1 15
  4. Calculate time diff:

    $ pdd -t 45:50 6:17:33
  5. Show current date, time and timezone:

    $ pdd
  6. Specify time with roll-over:

    $ pdd -t 5:80:75 6:17:33
  7. Add a duration (3 years, 2 months, 1 day) to 28 Feb, 2000:

    $ pdd -d 2000 FEB 28 3 2 1 --add
  8. Add a timeslice (1 hour 2 mins 3 secs) to 23:45:37:

    $ pdd -t 23:45:37 1:2:3 --add
  9. Add a duration (3 years, 2 months, 1 day) to today:

    $ pdd 3 2 1 --add
  10. Add a timeslice (1 hour 2 minutes 3 seconds) to now:

    $ pdd 1:2:3 --add
  11. Subtract a duration (1 day) from 1 Mar, 2000:

    $ pdd -d 2000 Mar 01 0 0 1 --sub
  12. Subtract a timeslice (1 sec) from midnight:

    $ pdd -t 00:00:00 0:0:1 --sub
  13. Subtract a duration (3 years, 2 months, 1 day) from today:

    $ pdd 3 2 1 --sub
  14. Subtract a timeslice (1 hour 2 minutes 3 seconds) from now:

    $ pdd 1:2:3 --sub
  15. Show the day of the week on 15 Jan 2014:

    $ pdd --day 2014 Jan 15
  16. Start a countdown timer or stopwatch in quiet mode in the background:

    $ pdd -qs &
    $ pdd -qc 3:0:0 &

    To see the final counter run fg and press Ctrl-C.

  17. Run a command when countdown timer reaches 0

    $ pdd -c 00:00:5 -r 'ps -aux'
    $ pdd -c 00:00:5 -r 'notify-send pdd "timer expired"'


Copyright © 2017 Arun Prakash Jana

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for pdd, version 1.4
Filename, size File type Python version Upload date Hashes
Filename, size pdd-1.4-py3-none-any.whl (20.6 kB) File type Wheel Python version py3 Upload date Hashes View hashes
Filename, size pdd-1.4.tar.gz (22.1 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page