python-libfaketime is a wrapper of libfaketime for python. Some brief details:
libfaketime.{begin, end}_callback to disable/enable your profiler (nosetest example).$ pip install libfaketime
import datetime
from libfaketime import fake_time, reexec_if_needed
# libfaketime needs to be preloaded by the dynamic linker.
# This will exec the same command, but with the proper environment variables set.
# You can also skip this and manually manage your env (see "How to avoid re-exec").
reexec_if_needed()
def test_datetime_now():
# fake_time can be used as a context_manager
with fake_time('1970-01-01 00:00:01'):
# Every calls to a date or datetime function returns the mocked date
assert datetime.datetime.utcnow() == datetime.datetime(1970, 1, 1, 0, 0, 1)
assert datetime.datetime.now() == datetime.datetime(1970, 1, 1, 0, 0, 1)
assert time.time() == 1
# fake_time can also be used as a decorator
@fake_time('1970-01-01 00:00:01', tz_offset=12)
def test_datetime_now_with_offset():
# datetime.utcnow returns the mocked datetime without offset
assert datetime.datetime.utcnow() == datetime.datetime(1970, 1, 1, 0, 0, 1)
# datetime.now returns the mocked datetime with the offset passed to fake_time
assert datetime.datetime.now() == datetime.datetime(1970, 1, 1, 12, 0, 1)
By default, reexec_if_needed removes the LD_PRELOAD variable after the
re-execution, to keep your environment as clean as possible. You might want it
to stick around, for example when using parallelized tests that use subprocess
like pytest-xdist, and simply for tests where subprocess is called. To
keep them around, pass remove_vars=False like:
reexec_if_needed(remove_vars=False)
To avoid displaying the informative text when re-executing, you can set the
quiet parameter:
reexec_if_needed(quiet=True)
A common time can be shared between several execution contexts by using a file to store the time to mock, instead of environment variables. This is useful to control the time of a running process for instance. Here is a schematized use case:
reexec_if_needed(remove_vars=False)
with fake_time("1970-01-01 00:00:00", timestamp_file="/tmp/timestamp"):
subprocess.run("/some/server/process")
with fake_time("2000-01-01 00:00:00", timestamp_file="/tmp/timestamp"):
assert request_the_server_process_date() == "2000-01-01 00:00:00"
libfaketime tends to be significantly faster than freezegun. Here's the output of a totally unscientific benchmark on my laptop:
$ python benchmark.py
re-exec with libfaketime dependencies
timing 1000 executions of <class 'libfaketime.fake_time'>
0.021755 seconds
$ python benchmark.py freezegun
timing 1000 executions of <function freeze_time at 0x10aaa1140>
6.561472 seconds
The pytest-libfaketime plugin will automatically configure python-libfaketime for you:
$ pip install pytest-libfaketime
Alternatively, you can reexec manually from inside the pytest_configure hook:
# conftest.py
import os
import libfaketime
def pytest_configure():
libfaketime.reexec_if_needed()
_, env_additions = libfaketime.get_reload_information()
os.environ.update(env_additions)
In your tox configuration file, under the testenv bloc, add the libfaketime environment variables to avoid re-execution:
setenv =
LD_PRELOAD = {envsitepackagesdir}/libfaketime/vendor/libfaketime/src/libfaketime.so.1
DONT_FAKE_MONOTONIC = 1
FAKETIME_DID_REEXEC = true
python-libfaketime should have the same behavior as freezegun when running on supported code. To migrate to it, you can run:
find . -type f -name "*.py" -exec sed -i 's/freezegun/libfaketime/g' "{}" \;
In some cases - especially when your tests start other processes - re-execing can cause unexpected problems. To avoid this, you can preload the necessary environment variables yourself. The necessary environment for your system can be found by running python-libfaketime on the command line:
$ python-libfaketime
export LD_PRELOAD="/home/foo/<snip>/vendor/libfaketime/src/libfaketime.so.1"
export DONT_FAKE_MONOTONIC="1"
export FAKETIME_NO_CACHE="1"
export FAKETIME_DID_REEXEC=true
You can easily put this in a script like:
$ eval $(python-libfaketime)
$ pytest # ...or any other code that imports libfaketime
Contributions are welcome! You should compile libfaketime before running tests:
git submodule init --update
# For Linux:
env FAKETIME_COMPILE_CFLAGS="-UFAKE_STAT -UFAKE_UTIME -UFAKE_SLEEP" make -C libfaketime/vendor/libfaketime
# For macOS
env make -C libfaketime/vendor/libfaketime
Then you can install requirements with pip install -r requirements.txt and use pytest and tox to run the tests.
Calling uuid.uuid1() multiple times while in a fake_time context can result in a deadlock when an OS-level uuid library is available.
To avoid this, python-libtaketime will monkeypatch uuid._uuid_generate_time (or similar, it varies by version) to None inside a fake_time context.
This may slow down uuid1 generation but should not affect correctness.
Semantic versioning is used.
released 2024-05-17
Thanks for @azmeuk for all their contributions to this release!
released 2020-04-17
released 2019-01-20
released 2018-10-28
released 2018-10-07
self._faked_time: #47released 2018-06-16
released 2018-05-19
released 2018-01-19
released 2017-09-10
released 2017-07-16
released 2017-07-07
released 2016-06-30
released 2016-05-02
released 2016-04-02
released 2016-03-04
libfaketime from the command line will now print the necessary environment to avoid a re-exec.released 2016-03-01
released 2015-09-11
released 2015-06-23
released 2015-03-28
FAQs
A fast alternative to freezegun that wraps libfaketime.
We found that libfaketime demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.