time-machine

Travel through time in your tests.

time-machine Permissive license MIT Active ★ 990 v3.4.0 released 2026-08-10

Install

time-machine on PyPI

pip

pip install time-machine

uv

uv add time-machine

poetry

poetry add time-machine

Package facts

License	MIT (permissive)
Python support	supports the current Python release (>=3.10)
Install friction	medium — platform-specific wheel
Runtime dependencies	none
Maintenance	actively maintained — 3 days since the last release
Last repo commit	2026-08-12
First released	2020-05-04
Popularity	one of the top 1,000 most-downloaded packages on PyPI (30-day window, as of 2026-08-13)
Known vulnerabilities	none known (OSV.dev, checked 2026-08-13)

Evidence: time_machine-3.4.0-cp310-cp310-macosx_10_9_x86_64.whl; time_machine-3.4.0-cp310-cp310-macosx_11_0_arm64.whl; time_machine-3.4.0-cp310-cp310-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl; time_machine-3.4.0-cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl; time_machine-3.4.0-cp310-cp310-musllinux_1_2_aarch64.whl; time_machine-3.4.0-cp310-cp310-musllinux_1_2_x86_64.whl; time_machine-3.4.0-cp310-cp310-win_amd64.whl; time_machine-3.4.0-cp310-cp310-win_arm64.whl; time_machine-3.4.0-cp311-cp311-macosx_10_9_x86_64.whl; time_machine-3.4.0-cp311-cp311-macosx_11_0_arm64.whl; time_machine-3.4.0-cp311-cp311-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl; time_machine-3.4.0-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl; time_machine-3.4.0-cp311-cp311-musllinux_1_2_aarch64.whl; time_machine-3.4.0-cp311-cp311-musllinux_1_2_x86_64.whl; time_machine-3.4.0-cp311-cp311-win_amd64.whl; time_machine-3.4.0-cp311-cp311-win_arm64.whl; time_machine-3.4.0-cp312-cp312-macosx_10_13_x86_64.whl; time_machine-3.4.0-cp312-cp312-macosx_11_0_arm64.whl; time_machine-3.4.0-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl; time_machine-3.4.0-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl

Keywords: date, datetime, mock, test, testing, tests, time, warp

Development Status :: 5 - Production/StableFramework :: PytestIntended Audience :: DevelopersNatural Language :: EnglishOperating System :: OS IndependentProgramming Language :: Python :: 3 :: OnlyProgramming Language :: Python :: 3.10Programming Language :: Python :: 3.11Programming Language :: Python :: 3.12Programming Language :: Python :: 3.13Programming Language :: Python :: 3.14Programming Language :: Python :: 3.15Typing :: Typed

About time-machine

from the package's own PyPI description — quoted content, verbatim

============ time-machine ============

.. image:: https://img.shields.io/readthedocs/time-machine?style=for-the-badge :target: https://time-machine.readthedocs.io/en/latest/

.. image:: https://img.shields.io/github/actions/workflow/status/adamchainz/time-machine/main.yml.svg?branch=main&style=for-the-badge :target: https://github.com/adamchainz/time-machine/actions?workflow=CI

.. image:: https://img.shields.io/badge/Coverage-100%25-success?style=for-the-badge :target: https://github.com/adamchainz/time-machine/actions?workflow=CI

.. image:: https://img.shields.io/pypi/v/time-machine.svg?style=for-the-badge :target: https://pypi.org/project/time-machine/

.. image:: https://img.shields.io/badge/code%20style-black-000000.svg?style=for-the-badge :target: https://github.com/psf/black

.. image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white&style=for-the-badge :target: https://github.com/pre-commit/pre-commit :alt: pre-commit

.. figure:: https://raw.githubusercontent.com/adamchainz/time-machine/main/docs/_static/logo.svg :alt: time-machine logo :align: center

Documentation

Please see...

Read as markdown · JSON record · Source repository · Docs

AI interpretation — verify before relying

AI-generated interpretation of the package facts above; every digit, version, license, or vulnerability id it cites is grounded in the facts already shown on this page

Mocks and freezes time in tests, allowing you to travel to any datetime and control how time advances during test execution.

Medium install friction due to compiled wheels across multiple Python versions and platforms (3.10–3.15, x86_64, ARM, Windows, macOS, Linux). Active maintenance with a release 3 days ago and 100% test coverage signal confidence in stability.

MIT license permits unrestricted use, modification, and distribution in both open-source and proprietary projects with minimal obligations.

Usage

pip install time-machine

from time_machine import travel
import datetime

with travel(datetime.datetime(2020, 1, 1)):
    assert datetime.datetime.now().year == 2020

Requires Python 3.10 or later; compiled extension wheels are provided but source builds may require a C compiler.

Verdict: Production-ready time-mocking library with active maintenance, zero known vulnerabilities, and permissive MIT licensing. The medium install friction reflects platform-specific compiled wheels rather than dependency complexity. Suitable for test suites that need deterministic datetime control.

Needs verification

Whether the package supports mocking time.time(), time.sleep(), and other time module functions beyond datetime
Compatibility with async/await and concurrent test execution patterns

mock datetime in testsfreeze time testingtime travel testingdatetime mocking librarycontrol time in pytesttest time-dependent codedatetime freezing