FAKETIME(1)

📦
version 0.9.13 · 6 versions
, in alpine 3.24, arch rolling

💜 faketime(1) 💜

okay so you opened the faketime(1) page from the wolfcw manual, section 1, and honestly? bestie, you're about to have the most fun a clock has ever had. let's get into it 🕰️✨

✨ NAME ✨

faketime — literally just messing with the system time for one specific command. that's it. that's the whole vibe 🎀

🌸 SYNOPSIS 🌸

faketime [options] timestamp program [arguments...]

🦋 DESCRIPTION 🦋

so here's the tea ☕ — the command you hand over gets tricked into believing the current system time is whatever you put in timestamp. no cap. and it's not just time() being lied to, either: filesystem timestamps also get reported relative to that timestamp. cute, right? 💅

the wall clock keeps running from that date and time you gave it, unless you say otherwise — that's the advanced options territory, we'll get there, don't worry 🫶

under the hood, faketime is really just a simple little wrapper around libfaketime, which uses the LD_PRELOAD mechanism to load a small library that intercepts system calls to functions like time(2) and fstat(2). iconic behavior, honestly.

heads up tho — this wrapper only exposes a subset of libfaketime's functionality. for the full menu please go read the README file that came with faketime for more details and advanced options, or peek at https://github.com/wolfcw/libfaketime 🌈

💖 OPTIONS 💖

  • --help — shows the usage info and dips out. bye 👋
  • --version — shows version info and also dips out.
  • -m — uses the multi-threading variant of libfaketime. multitasking queen energy 🧚
  • -p <PID> — pretend the program's process ID is PID. (this one's only available if it was built with FAKE_PID, so don't come for me if it's missing 🙈)
  • -f — use the advanced timestamp specification format. the fancy one. the main character one 👑
  • --exclude-monotonic — do not fake the time when the program makes a call to clock_gettime with a CLOCK_MONOTONIC clock. hands off that one 🚫
  • --disable-shm — disables libfaketime's use of shared memory.
  • --date-prog <PATH> — use a specific GNU-date-compatible implementation of the helper that transforms "timestamp format" strings into programmatically usable dates, instead of a compile-time default guess for the generic target platform. iykyk 🔥

🌟 EXAMPLES 🌟

faketime 'last Friday 5 pm' date
faketime '2008-12-24 08:15:42' date
faketime -f '+2,5y x10,0' bash -c 'date; while true; do echo $SECONDS ; sleep 1 ; done'
faketime -f '+2,5y x0,50' bash -c 'date; while true; do echo $SECONDS ; sleep 1 ; done'
faketime -f '+2,5y i2,0' bash -c 'while true; do date ; sleep 1 ; done'

In this single case all spawned processes will use the same global clock without restarting it at the start of each process. 👯‍♀️💫

(Please note that it depends on your locale settings whether . or , has to be used for fractional offsets) — the little comma/period drama we all love 😭

🎀 ADVANCED TIMESTAMP FORMAT 🎀

okay so the simple timestamp format (the default one) just applies the /bin/date -d command to parse user-friendly specs like 'last friday'. easy, adorable, works.

but when you use the -f option, the timestamp you typed on the command line is passed directly to libfaketime, and that unlocks a whole extra set of features — like speeding the clock up or slowing it down for the target program. slay. it is strongly recommended that you have a look at the libfaketime documentation before going wild with this. here's the summary:

❄️ Freeze clock at absolute timestamp: "YYYY-MM-DD hh:mm:ss"

if you want an absolute point in time, exactly this format must be used. and listen — freezing the clock is usually not what you want, and it may absolutely break the application. only use if you know what you're doing! ⚠️💀

⏩ Relative time offset: "[+/-]123[m/h/d/y]", e.g., "+60m", "+2y"

this is the most often used format and it specifies the faked time relatively to the current real time. the first character of the format string must be a + or a -. the numeric value by default represents seconds, but the modifiers m, h, d, and y can be used to specify minutes, hours, days, or years, respectively.

for example, "-2y" means "two years ago". 💫

fractional time offsets can be used too — e.g. "+2,5y", which means "two and a half years in the future". but please note that the fraction delimiter depends on your locale settings, so if "+2,5y" doesn't work, try "+2.5y" instead. annoying, i know, but we move 🫠

🚀 Start-at timestamps: "@YYYY-MM-DD hh:mm:ss"

the wall clock will start counting at the given timestamp for the program. this is how you specify absolute timestamps without freezing the clock. much better, honestly ✨

🔥 ADVANCED USAGE 🔥

when you're using relative time offsets or start-at timestamps (that's the ADVANCED TIMESTAMP FORMAT section above, plus option -f), you can adjust the clock speed — meaning time can run faster or slower for the executed program. wild, right?

for example, "+5y x10" sets the faked time 5 years into the future and makes time pass 10 times as fast (one real second equals 10 seconds as measured by the program). ⏱️💨

similarly, you can slow the flow of time, e.g. "-7d x0,2", which sets the faked time 7 days in the past and sets the clock speed to 20 percent — i.e. it takes five real-world seconds for one second measured by the program. slow burn aesthetic 🐌💜

and again: depending on your locale, either "x2.0" or "x2,0" may be required regarding the delimiter. (we've been through this, i know 😭)

you can also make faketime advance the reported time by a preset interval upon each time() call, independently from the system's time, using "-7d i2,0" — where i is followed by the increase interval in seconds. periodt. 💅

faking times for multiple programs — or even system-wide — can be simplified by using ~/.faketimerc files and /etc/faketimerc. please refer to the README that came with faketime for warnings and details. 🫶

and one more thing: faking of filesystem timestamps may be disabled by setting the NO_FAKE_STAT environment variable to a non-empty value. ✨

👑 AUTHOR 👑

Please see the README and NEWS files for contributors. (yes, the actual author credit lives over there, go show them love 💖)

💀 BUGS 💀

alright, deep breath, here's the fine print — because of limitations of the LD_PRELOAD mechanism, faketime will not work with suidroot and statically linked programs. sorry, that's just how it is 🙈

while timestamps and time offsets will work for child processes, speeding the clock up or slowing it down might not work for child processes spawned by the executed program as expected — a new instance of libfaketime is used for each child process, which means that the libfaketime start time (the thing used in speed adjustments) will also be re-initialized. so the vibe resets. annoying but true 😭

some programs may dynamically load system libraries, such as librt, at run-time and therefore bypass libfaketime entirely. rude.

you may report programs that do not work with libfaketime — but only if they are available as open source. that's the deal 🤝

🐛 REPORTING BUGS 🐛

Please use https://github.com/wolfcw/libfaketime/issues — the issue tracker is right there, bestie, use it 🫶

Copyright © 2003-2021 by the libfaketime authors.

there is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. like, none. zero. ✨

you may redistribute copies of faketime under the terms of the GNU General Public License. for more information about these matters, see the file named COPYING. 📜

⭐ SEE ALSO ⭐

and that's the whole page, bestie 💅 faketime 0.9.13, dated August 2026 — go forth and lie to clocks responsibly, ily, mwah 🎀🦋💜

📦 where this page comes from