time-machine

3.2.0 · active · verified Sun Mar 29

time-machine is a Python library that enables 'time travel' in your tests by mocking Python's standard library functions that return the current date or datetime. It achieves this efficiently using C extensions, providing a fast and robust solution for time-dependent testing. The library is actively maintained, with version 3.2.0 released in December 2025.

Warnings

gotcha Time is a global state. When mocking time with `time-machine`, all concurrent threads or asynchronous functions within the same process will also be affected. This can lead to unexpected behavior if not accounted for.
Fix: Be aware of the global nature of time mocking in multithreaded or asynchronous tests. Design tests to isolate time-sensitive operations or use careful synchronization.
gotcha `time-machine` only mocks Python's standard library functions for time. It does not affect other processes (e.g., database servers, external APIs) or libraries that make direct C-level system calls for time.
Fix: For external systems, mock the external system's responses directly rather than relying on `time-machine`.
gotcha `time-machine` currently only works with CPython (the standard Python interpreter) and is not compatible with other Python interpreters like PyPy.
Fix: Ensure your testing environment uses CPython if `time-machine` is a dependency.
breaking As of version 3.0.0, `time-machine` no longer mocks `time.monotonic()` and `time.monotonic_ns()`. Mocking these functions caused significant issues with asyncio event loops, test duration measurements, and other libraries relying on a strictly monotonic clock.
Fix: If you need to mock `time.monotonic()` or `time.monotonic_ns()`, use `unittest.mock` or a similar patching mechanism manually, but be aware of potential side effects.
breaking The `tz_offset` argument for specifying timezones was removed in version 2.0.0. Timezones should now be specified by providing a `datetime` object with a `zoneinfo.ZoneInfo` instance attached (Python 3.9+ or `backports.zoneinfo`).
Fix: Update `time_machine.travel` calls to pass a timezone-aware `datetime` object (e.g., `dt.datetime(..., tzinfo=ZoneInfo('America/Los_Angeles'))`) instead of `tz_offset`.
gotcha The default `naive_mode` for interpreting naive datetimes is `MIXED`, which can be confusing (naive `datetime` objects are UTC, strings are local). It's recommended to explicitly set `naive_mode` to `LOCAL` or `ERROR` for consistent and clearer behavior.
Fix: Set `time_machine.naive_mode = time_machine.LOCAL` or `time_machine.naive_mode = time_machine.ERROR` in your test setup to enforce a consistent interpretation.
gotcha Attempting to start time travel with `time-machine` when `freezegun` (another time-mocking library) is already active will raise a `RuntimeError` to prevent conflicts and ensure a clean state for mocking.
Fix: Ensure that `freezegun` is not active in the same process where `time-machine` is being used. If migrating, use the provided `time_machine migrate` CLI tool.

Install

pip install time-machine Install latest version

Imports

travel
```
from time_machine import travel
```
is_travelling
```
from time_machine import is_travelling
```
naive_mode
```
from time_machine import naive_mode
```

Quickstart

Demonstrates `time-machine` as a decorator and context manager to fix the current time for testing.

import datetime as dt
import time_machine

@time_machine.travel("1955-11-05 01:22")
def test_delorean():
    assert dt.date.today().isoformat() == "1955-11-05"

def use_context_manager():
    with time_machine.travel(dt.datetime(1985, 10, 26, 1, 24, tzinfo=dt.timezone.utc)):
        assert dt.datetime.now(dt.timezone.utc).year == 1985

# To run the example (in a test framework like pytest, this would be automatic):
if __name__ == "__main__":
    test_delorean()
    use_context_manager()
    print("Quickstart example ran successfully!")

view raw JSON →