Useful extensions to the standard Python datetime features
Python Other
Clone or download
pganssle Merge pull request #801 from pganssle/invalid_tz
Stop trying to add None to the weakref cache
Latest commit a5d860d Aug 14, 2018
Failed to load latest commit information.
.github Add pull request template Apr 14, 2018
changelog.d Stop trying to store None in weakref cache Aug 14, 2018
ci_tools Add scripts to test against tz master Jul 2, 2018
dateutil Modify badzone test and add new xfail Aug 14, 2018
docs Merge pull request #762 from prdickson/#623-no-docs-for-rrulestr Jun 20, 2018
.gitattributes Switch line endings for batch files to CRLF Mar 30, 2016
.gitignore Add mypy_cache to gitignore Apr 17, 2018
.travis.yml Pin setuptools on Python 3.3 Aug 11, 2018 Add Bradlee Speice to AUTHORS Aug 11, 2018 Specifies directory for changelog entries Jun 21, 2018
LICENSE Update license with Apache 2.0 and AUTHORS file Dec 6, 2017 Fix issue with test inclusion. Mar 15, 2016
NEWS Add changelog to documentation Apr 24, 2018
README.rst Add installation information to the README Jul 2, 2018
RELEASING Convert readthedocs link for their .org -> .io migration for hosted p… May 29, 2016
appveyor.yml Using exclude to reduce jobs in matrix Dec 11, 2017
codecov.yml Disable patch and changes. May 7, 2016
pyproject.toml pyproject.toml: add setuptools, wheel and setuptools_scm to 'build-sy… Jun 8, 2018 Added script to help with releases. Jul 10, 2017
requirements-dev.txt Hypothesis tests on convertyear Apr 15, 2018
setup.cfg Set all warnings as errors in pytest Jun 22, 2018 Remove requires from Jun 8, 2018
tox.ini Run test suite against custom system zoneinfo files Jul 2, 2018 Make updatezinfo take metadata file from CLI Jul 2, 2018
zonefile_metadata.json Update zonefile to 2018e May 4, 2018


dateutil - powerful extensions to datetime

pypi version supported Python version licence

Join the chat at Read the documentation at

travis build status appveyor build status Code coverage

The dateutil module provides powerful extensions to the standard datetime module, available in Python.


dateutil can be installed from PyPI using pip (note that the package name is different from the importable name):

pip install python-dateutil


dateutil is available on PyPI

The documentation is hosted at:


The code and issue tracker are hosted on Github:


  • Computing of relative deltas (next month, next year, next monday, last week of month, etc);
  • Computing of relative deltas between two given date and/or datetime objects;
  • Computing of dates based on very flexible recurrence rules, using a superset of the iCalendar specification. Parsing of RFC strings is supported as well.
  • Generic parsing of dates in almost any string format;
  • Timezone (tzinfo) implementations for tzfile(5) format files (/etc/localtime, /usr/share/zoneinfo, etc), TZ environment string (in all known formats), iCalendar format files, given ranges (with help from relative deltas), local machine timezone, fixed offset timezone, UTC timezone, and Windows registry-based time zones.
  • Internal up-to-date world timezone information based on Olson's database.
  • Computing of Easter Sunday dates for any given year, using Western, Orthodox or Julian algorithms;
  • A comprehensive test suite.

Quick example

Here's a snapshot, just to give an idea about the power of the package. For more examples, look at the documentation.

Suppose you want to know how much time is left, in years/months/days/etc, before the next easter happening on a year with a Friday 13th in August, and you want to get today's date out of the "date" unix system command. Here is the code:

>>> from dateutil.relativedelta import *
>>> from dateutil.easter import *
>>> from dateutil.rrule import *
>>> from dateutil.parser import *
>>> from datetime import *
>>> now = parse("Sat Oct 11 17:13:46 UTC 2003")
>>> today =
>>> year = rrule(YEARLY,dtstart=now,bymonth=8,bymonthday=13,byweekday=FR)[0].year
>>> rdelta = relativedelta(easter(year), today)
>>> print("Today is: %s" % today)
Today is: 2003-10-11
>>> print("Year with next Aug 13th on a Friday is: %s" % year)
Year with next Aug 13th on a Friday is: 2004
>>> print("How far is the Easter of that year: %s" % rdelta)
How far is the Easter of that year: relativedelta(months=+6)
>>> print("And the Easter of that year is: %s" % (today+rdelta))
And the Easter of that year is: 2004-04-11

Being exactly 6 months ahead was really a coincidence :)


We welcome many types of contributions - bug reports, pull requests (code, infrastructure or documentation fixes). For more information about how to contribute to the project, see the file in the repository.


The dateutil module was written by Gustavo Niemeyer <> in 2003.

It is maintained by:

Starting with version 2.4.1, all source and binary distributions will be signed by a PGP key that has, at the very least, been signed by the key which made the previous release. A table of release signing keys can be found below:

Releases Signing key fingerprint
2.4.1- 6B49 ACBA DCF6 BD1C A206 67AB CD54 FCE3 D964 BEFB (mirror)


Our mailing list is available at As it is hosted by the PSF, it is subject to the PSF code of conduct.


All contributions after December 1, 2017 released under dual license - either Apache 2.0 License or the BSD 3-Clause License. Contributions before December 1, 2017 - except those those explicitly relicensed - are released only under the BSD 3-Clause License.