time-machine

library3.5.0pypypi✓ verified 26d ago

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.

testing

pip install time-machine

github ↗package ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · TIME-MACHINE

time-machine

testingpythonv3.5.0

Install

1.7s avg

Import

190ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.5.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.206s · 18MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.7s · import 0.174s · 19MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

travel

✓ from time_machine import travel

is_travelling

✓ from time_machine import is_travelling

naive_mode

✓ from time_machine import naive_mode

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!")

Debug

Known issues

gotchaTime 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.

affects: All versions

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`.

affects: All versions

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.

affects: All versions

breakingAs 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.

affects: >=3.0.0

breakingThe `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`.

affects: >=2.0.0

gotchaThe 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.

affects: All versions

gotchaAttempting 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.

affects: >=3.2.0

Errors

Common errors & fixes

error: command 'gcc' failed with exit status 1

The C extension for `time-machine` failed to compile during installation, often due to missing build tools or Python development headers.

fix

Ensure development tools and Python development headers are installed for your operating system (e.g., `sudo apt-get install build-essential python3-dev` on Debian/Ubuntu, or Xcode command line tools on macOS).

import time-machine

Python module names cannot contain hyphens; the library's Python package name uses an underscore.

fix

Use `import time_machine` instead.

TypeError: travel() missing 1 required positional argument: 'destination'

The `time_machine.travel()` function requires a `destination` argument, which specifies the point in time to travel to.

fix

Provide a valid destination like a datetime string, a `datetime` object, `date` object, or a float timestamp, e.g., `time_machine.travel('2023-01-01')`.

TypeError: Expected str, datetime.datetime, datetime.date, or float, got NoneType

The `destination` argument provided to `time_machine.travel()` was of an unsupported type (e.g., `None`), instead of a string, `datetime`, `date`, or float.

fix

Ensure the `destination` argument is one of the supported types, for example, `'2024-01-01 10:00:00'` or `datetime.datetime(2024, 1, 1, 10, 0, 0)`.

ValueError: Invalid destination: "invalid-date-string"

The string provided as the `destination` argument to `time_machine.travel()` could not be parsed into a valid date or datetime.

fix

Provide a valid, unambiguous date or datetime string, such as `'YYYY-MM-DD'`, `'YYYY-MM-DD HH:MM:SS'`, or an ISO 8601 formatted string.

Upgrade

Version history

3.5.0latest on PyPI · released Aug 25, 2026

Audit

Dependencies

backports.zoneinfooptionalRequired for `zoneinfo.ZoneInfo` support on Python versions older than 3.9 when mocking timezones.

python-dateutiloptionalNeeded for parsing string destinations (e.g., 'YYYY-MM-DD') if not providing explicit datetime objects.

Agent activity

12 hits · last 30 days

node

Resources

githubhttps://github.com/adamchainz/time-machine ↗

packagehttps://pypi.org/project/time-machine/ ↗

docshttps://time-machine.readthedocs.io/ ↗

changeloghttps://time-machine.readthedocs.io/en/latest/changelog.html ↗