time-machine
time-machine is a Python testing library that lets developers mock or freeze time during unit tests. It intercepts time-related system calls to simulate traveling to any point in the past or future, making it easier to test time-dependent code without waiting or using the actual system clock.
Key facts
Objective fields from the source. Values we can't verify are shown as “Unknown” rather than guessed.
| Field | Value |
|---|---|
| Repository | adamchainz/time-machine |
| Owner | adamchainz |
| Primary language | Python |
| License | MIT — OSI-approved |
| Stars | 979 |
| Forks | 48 |
| Open issues | 25 |
| Latest release | Unknown |
| Last updated | 2026-07-06 |
| Source | https://github.com/adamchainz/time-machine |
What time-machine is
A Python package that patches time-related builtins and standard library functions (datetime, time, etc.) to allow tests to control the current time state. It supports context managers and decorators for granular time manipulation within test scopes, with 100% test coverage reported.
Get the time-machine source
Clone the repository and explore it locally.
git clone https://github.com/adamchainz/time-machine.gitcd time-machine# follow the project's README for install & configurationNeed it deployed, integrated, or customized instead? DEV.co ships production installs.
Best use cases
Implementation considerations
- Ensure all time-dependent code uses standard Python datetime/time modules; third-party or custom time implementations may not be patched.
- Test isolation: time state persists across test methods unless explicitly reset; use context managers or decorators to scope changes.
- Verify behavior with libraries that cache datetime objects at import time (e.g., logging formatters, cache headers) as they may see stale values.
- Confirm compatibility with your Python version and test runner (pytest, unittest, etc.) before adoption.
- Document mocking strategy in test setup to make time freezing explicit to future maintainers.
When to avoid it — and what to weigh
- Testing async/concurrent time behavior — Project documentation does not explicitly confirm thread-safe or async-compatible time patching; concurrency bugs may not be caught.
- Integration tests requiring real system clock — If tests need to interact with external services that validate wall-clock time server-side, mocking client-side time may cause failures.
- Testing C extensions or native code directly — time-machine patches Python-level time calls; compiled code or system calls that bypass Python bindings will not be affected.
- Projects requiring clock adjustment during test execution — No evidence of support for incrementally advancing time in sub-second intervals; only snapshot/freeze-then-jump workflows are documented.
License & commercial use
MIT License permits unrestricted use, modification, and distribution in proprietary and open-source projects, provided copyright and license text are retained.
MIT is a permissive OSI-approved license with no commercial restrictions. Use in proprietary products is permitted; however, ensure your legal team reviews license attribution requirements for your distribution method.
DEV.co evaluation signals
Editorial assessment — not user reviews. Directional, with an explicit confidence level.
| Signal | Assessment |
|---|---|
| Maintenance | Active |
| Documentation | Strong |
| License clarity | Clear |
| Deployment complexity | Low |
| DEV.co fit | Good |
| Assessment confidence | High |
time-machine patches Python's time representation at the interpreter level during tests. Review implications: (1) ensure test and production code paths are clearly separated to avoid mocked time in production, (2) validate no sensitive time-based security logic (e.g., token expiry checks) relies on patched time in unexpected contexts, (3) confirm usage does not mask real timing bugs (e.g., performance regressions) that integration tests should catch.
Alternatives to consider
freezegun
Popular alternative with similar scope (freeze/mock time); may have broader decorator/context support or different patching strategy. Compare if time-machine doesn't cover your use case.
pytest-freezegun
Pytest-specific plugin wrapping freezegun; tighter integration with pytest fixtures if that's your test runner.
unittest.mock with patch
Standard library approach; less specialized but requires manual patching of every time call. Useful if you want zero external dependencies.
Build on time-machine with DEV.co software developers
Adopt time-machine to eliminate flaky tests, reduce test execution time, and reliably reproduce timezone and deadline scenarios. Review the documentation and integrate it into your test suite today.
Talk to DEV.coRelated open-source tools
Surfaced by semantic similarity across the DEV.co open-source index.
Related on DEV.co
Explore the category and the services that help you build with it.
time-machine FAQ
Does time-machine work with async code?
Can I run multiple time-travel operations in parallel test runs?
Will mocked time affect external services or databases?
What Python versions are supported?
Custom software development services
Need help beyond evaluating time-machine? DEV.co is a software development agency offering software development services and web development for teams of every size. Our software developers and web developers build custom software, web applications, APIs, and open-source testing integrations — and maintain them long-term.
Ready to simplify time-dependent testing?
Adopt time-machine to eliminate flaky tests, reduce test execution time, and reliably reproduce timezone and deadline scenarios. Review the documentation and integrate it into your test suite today.