faketime

Fake the time to this evening, before printing the result of date

$ faketime '[today 23:30]' [date]

$ faketime '[yesterday]' [bash]

$ faketime '[next Friday 1 am]' [path/to/program]

faketime [options] timestamp command [arguments...]

--help
    Displays a help message and exits.

--version
    Outputs version information and exits.

-m, --monotonous
    Causes the monotonic clock (CLOCK_MONOTONIC) to also start at the fake time, maintaining a consistent offset from the real monotonic clock.

-p, --pretty
    Prints the current fake time to standard error before executing the command, providing a quick verification.

-r, --realtime
    Ensures the monotonic clock proceeds with real time, even if -m is used. Useful for specific scenarios where a fixed fake time is desired for the wall clock but real time progression for monotonic.

-f <file>, --file <file>
    Reads the FAKETIME setting from the specified file instead of directly from the command line or environment variable.

-l <lib>, --load <lib>
    Specifies an alternative libfaketime.so library to preload, useful for custom or debug versions.

faketime is a command-line utility for Linux and other Unix-like systems that allows you to run a program as if the system time were different from the actual current time. It achieves this by intercepting calls to standard time-related library functions (like time(), gettimeofday(), clock_gettime()) using the LD_PRELOAD mechanism. Instead of returning the real system time, faketime's injected library (libfaketime.so) returns a time based on the user-specified offset or absolute timestamp.

This functionality is invaluable for testing time-sensitive applications, simulating future or past events, debugging date-related bugs, or replicating specific scenarios without needing to manually change the system-wide clock. Importantly, faketime only affects the targeted program and its child processes, leaving the rest of the system's time unchanged. Users can specify an absolute timestamp or a relative offset (e.g., "+10d" for 10 days in the future). This tool provides a powerful and isolated environment for time manipulation.

faketime relies on the LD_PRELOAD mechanism, which means it primarily works for dynamically linked executables. It generally does not affect:
Kernel-level operations or hardware clocks.
SUID/SGID binaries due to security restrictions that often prevent `LD_PRELOAD` from being honored.
Programs that use alternative, non-standard methods to obtain time (e.g., directly querying NTP servers or using very low-level hardware timers).
File modification times (mtime, ctime) of files created or modified by the faked program.
System logs that record real time.

Beyond the faketime command-line wrapper, the core functionality can be achieved by directly setting the FAKETIME environment variable before executing a command.

Example: FAKETIME="+1y" my_program
This allows for direct integration into scripts or makefiles without the explicit faketime command. The same timestamp formats apply.

faketime supports a variety of timestamp formats for specifying the desired fake time:

Absolute Time:
    YYYY-MM-DD HH:MM:SS (e.g., 2025-01-01 10:00:00)
    @YYYY-MM-DD HH:MM:SS (e.g., @2025-01-01 10:00:00) - Useful when the command itself starts with a '+' or '-'.
Relative Time:
    +N[yMwdHMS] (e.g., +10d for 10 days in the future, +1h30m for 1 hour 30 minutes)
    -N[yMwdHMS] (e.g., -5y for 5 years in the past)
Fixed Time and Progression:
    start-at-timestamp[xmultiplier] (e.g., "2020-01-01 10:00:00x2" to start at a specific time and progress at twice the real speed).

faketime emerged as a practical solution to a common problem in software development and testing: the need to test time-sensitive applications without altering the system-wide clock. Prior to tools like faketime, developers often resorted to manually changing system dates, which was cumbersome and could disrupt other running processes. Leveraging the dynamic linker's LD_PRELOAD capability, faketime provides an elegant and isolated method for time manipulation. It has been actively developed and maintained within the open-source community, becoming a de-facto standard for time-mocking in Unix-like environments due to its robustness and ease of use.

date(1): System date and time display/setting utility., strace(1): Traces system calls and signals, useful for observing which time-related calls a program makes., ld.so(8): Dynamic linker/loader, which handles the LD_PRELOAD mechanism., hwclock(8): Utility for querying and setting the hardware clock.