# Freezegun: Time Travel for Your Python Tests

This repository profile is provided by osrepos.com, an open source repository discovery platform.

Source: osrepos.com
Repository profile: https://osrepos.com/repo/spulec-freezegun
Generated for open source discovery and AI-assisted research.

Freezegun is a powerful Python library designed to simplify testing by allowing your tests to travel through time. It achieves this by mocking the `datetime` module, enabling developers to freeze time at a specific point or even simulate its progression. This functionality is crucial for ensuring consistent and reliable test results when dealing with time-sensitive logic.

GitHub: https://github.com/spulec/freezegun
OSRepos URL: https://osrepos.com/repo/spulec-freezegun

## Summary

Freezegun is a powerful Python library designed to simplify testing by allowing your tests to travel through time. It achieves this by mocking the `datetime` module, enabling developers to freeze time at a specific point or even simulate its progression. This functionality is crucial for ensuring consistent and reliable test results when dealing with time-sensitive logic.

## Topics

- Python
- Testing
- Mocking
- Datetime
- Time
- Development
- Library

## Repository Information

Last analyzed by OSRepos: Tue Aug 04 2026 01:00:03 GMT+0100 (Western European Summer Time)
Detail views: 0
GitHub clicks: 0

## Safety Notice

OSRepos shares public repositories for knowledge and discovery only. Review source code, dependencies, licenses, and security implications before running or installing anything.

## Content

## Introduction

Freezegun is an indispensable Python library that empowers developers to manipulate time within their test suites. By effectively mocking the `datetime` module, `time.time()`, and related functions, Freezegun allows you to freeze the current time to a specific date and time, or even simulate the passage of time. This capability is vital for testing applications with time-dependent features, ensuring that your tests are deterministic and free from real-world time variations.

## Installation

Installing Freezegun is straightforward using pip:

bash
$ pip install freezegun


For Debian systems, you can also use apt-get:

bash
$ sudo apt-get install python-freezegun


## Examples

Freezegun offers flexible ways to control time, whether through decorators, context managers, or direct API calls.

### Decorator Usage

Apply `freeze_time` as a decorator to functions or classes to freeze time for their duration.

python
from freezegun import freeze_time
import datetime
import unittest

# Freeze time for a pytest style test:
@freeze_time("2012-01-14")
def test_frozen_time_decorator():
    assert datetime.datetime.now() == datetime.datetime(2012, 1, 14)

# Or a unittest TestCase:
@freeze_time("1955-11-12")
class MyTests(unittest.TestCase):
    def test_the_class(self):
        assert datetime.datetime.now() == datetime.datetime(1955, 11, 12)


### Context Manager Usage

Use `freeze_time` as a context manager for precise control over time within a specific block of code.

python
from freezegun import freeze_time
import datetime

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


### Manual Ticks and Moving Time

Beyond freezing, Freezegun allows you to manually advance time or jump to a specific date.

python
from freezegun import freeze_time
import datetime

def test_manual_tick_and_move():
    initial_datetime = datetime.datetime(year=1, month=7, day=12,
                                        hour=15, minute=6, second=3)
    with freeze_time(initial_datetime) as frozen_datetime:
        assert frozen_datetime() == initial_datetime

        # Manually advance time by 1 second
        frozen_datetime.tick()
        initial_datetime += datetime.timedelta(seconds=1)
        assert frozen_datetime() == initial_datetime

        # Move to a completely different date
        other_datetime = datetime.datetime(year=2, month=8, day=13,
                                            hour=14, minute=5, second=0)
        frozen_datetime.move_to(other_datetime)
        assert frozen_datetime() == other_datetime


### Ticking Time

The `tick=True` argument allows time to progress naturally from the frozen point.

python
from freezegun import freeze_time
import datetime
import time

@freeze_time("Jan 14th, 2020", tick=True)
def test_ticking_time():
    # Time will progress naturally after the initial freeze point
    initial_time = datetime.datetime.now()
    time.sleep(0.01) # Simulate some time passing
    assert datetime.datetime.now() > initial_time


### Auto-Ticking Time

The `auto_tick_seconds` argument automatically increments time by a specified amount on each call.

python
from freezegun import freeze_time
import datetime

@freeze_time("Jan 14th, 2020", auto_tick_seconds=15)
def test_auto_ticking_time():
    first_time = datetime.datetime.now()
    # Subsequent call to datetime.datetime.now() will be 15 seconds later
    auto_incremented_time = datetime.datetime.now()
    assert first_time + datetime.timedelta(seconds=15) == auto_incremented_time


### Real Asyncio

For `asyncio` applications, `real_asyncio=True` allows `asyncio` event loops to see real monotonic time while `datetime` remains frozen.

python
from freezegun import freeze_time
import datetime
import asyncio

@freeze_time("2012-01-14", real_asyncio=True)
async def test_asyncio_with_frozen_time():
    start_time = datetime.datetime.now()
    await asyncio.sleep(0.1) # This sleep will use real time
    end_time = datetime.datetime.now()
    assert start_time == end_time # datetime is still frozen


## Why Use Freezegun?

Testing applications that interact with dates and times can be notoriously difficult. Real-world time is constantly changing, making it hard to reproduce specific scenarios or ensure consistent test results. Freezegun solves this by providing a simple, elegant way to control time within your tests. This leads to more reliable, deterministic, and faster test suites, allowing you to focus on your application's logic rather than battling time-related inconsistencies. It's an essential tool for any Python developer working with `datetime` objects in their code.

## Links

Explore the Freezegun project further:

*   [GitHub Repository](https://github.com/spulec/freezegun){:target="_blank"}
*   [PyPI Page](https://pypi.python.org/pypi/freezegun/){:target="_blank"}