Node.js Reference ยท fs and fs/promises
Node.js fs.utimes() method
Reference for fs.utimes(), futimes() and lutimes() in Node.js: set atime and mtime with seconds or Dates, precision limits, symlinks and what cannot be changed.
fs.utimes(path, atime, mtime, callback) sets a file's last-access time and last-modification time. It is what the touch -d command does. Typical uses are restoring timestamps after copying or unpacking files, making build tools treat a file as fresh or stale, and preparing known timestamps for tests.
The one thing that trips people up: the time arguments given as numbers are seconds since the Unix epoch, not milliseconds like Date.now(). Passing a Date object avoids the confusion.
import fs from "node:fs"; const when = new Date("2025-01-01T00:00:00Z"); fs.utimesSync("report.pdf", when, when);
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Syntax
fs.utimes(path, atime, mtime, callback) fs.utimesSync(path, atime, mtime): undefined fsPromises.utimes(path, atime, mtime): Promise<undefined> fs.futimes(fd, atime, mtime, callback) // also filehandle.utimes(atime, mtime) fs.lutimes(path, atime, mtime, callback) // acts on a symlink itself
| Name | Description |
|---|---|
atime |
New access time: a Date, a number of seconds since the epoch, or a numeric string. |
mtime |
New modification time, same types. |
path |
A string, Buffer or URL. utimes follows symbolic links. |
fd |
An open file descriptor, for futimes. |
Returns: undefined.
Errors: ENOENT for a missing path, EPERM if you are not the owner (and not root), EROFS on a read-only file system, ERR_INVALID_ARG_TYPE for values that are not dates, numbers or numeric strings.
Usage notes
- Seconds, not milliseconds.
fs.utimes(file, Date.now(), Date.now())asks for a year around 55,000, which the file system rejects, clamps or stores as nonsense. Divide by 1000 or pass aDate. - Precision depends on the file system. FAT stores two-second steps for modification times; ext4 and NTFS keep much finer resolution. Reading the value back can differ slightly from what you set, so compare with a tolerance.
- You cannot set
ctimeorbirthtime.ctimeis updated to "now" by the very act of changing the times. - Reading a file updates
atimeon some systems and not on others (noatimeandrelatimemount options). Do not rely on it as an access log. - Writing a file sets
mtimeagain, so applyutimeslast. - Only the owner or root may set arbitrary times; other users can only set them to the current time.
lutimes()(Node 14.5+) is the symlink-safe variant. It needs operating system support and throws on platforms without it.- Build tools: comparing
mtimeMsof inputs and outputs is the classic "is it stale" check.