Skip to main content
Join the official Python Developers Survey 2018 and win valuable prizes: Start the survey!

Let your Python tests travel through time

Project description

FreezeGun is a library that allows your python tests to travel through time by mocking the datetime module.


Once the decorator or context manager have been invoked, all calls to, datetime.datetime.utcnow(),, time.time(), time.localtime(), time.gmtime(), and time.strftime() will return the time that has been frozen.


from freezegun import freeze_time

def test():
    assert == datetime.datetime(2012, 01, 14)

# Or class based

class Tester(object):
    def test_the_class(self):
        assert == datetime.datetime(2012, 01, 14)

Context Manager

from freezegun import freeze_time

def test():
    assert != datetime.datetime(2012, 01, 14)
    with freeze_time("2012-01-14"):
        assert == datetime.datetime(2012, 01, 14)
    assert != datetime.datetime(2012, 01, 14)

Raw use

from freezegun import freeze_time

freezer = freeze_time("2012-01-14 12:00:01")
assert == datetime.datetime(2012, 01, 14, 12, 00, 01)


from freezegun import freeze_time

@freeze_time("2012-01-14 03:21:34", tz_offset=-4)
def test():
    assert datetime.datetime.utcnow() == datetime.datetime(2012, 01, 14, 03, 21, 34)
    assert == datetime.datetime(2012, 01, 13, 23, 21, 34)

    # uses local time
    assert == datetime.datetime(2012, 01, 13)

Nice inputs

FreezeGun uses dateutil behind the scenes so you can have nice-looking datetimes

@freeze_time("Jan 14th, 2012")
def test_nice_datetime():
    assert == datetime.datetime(2012, 01, 14)


To install FreezeGun, simply:

$ pip install freezegun

On Debian (Testing and Unstable) systems:

$ sudo apt-get install python-freezegun

Project details

Download files

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

Filename, size & hash SHA256 hash help File type Python version Upload date
freezegun-0.3.1-py2.py3-none-any.whl (5.2 kB) Copy SHA256 hash SHA256 Wheel 2.7 Feb 16, 2015
freezegun-0.3.1.tar.gz (40.3 kB) Copy SHA256 hash SHA256 Source None Feb 16, 2015

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 SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page