Skip to content
Tutorials Center
My learning

Topics

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.

NODE
import fs from "node:fs";

const when = new Date("2025-01-01T00:00:00Z");
fs.utimesSync("report.pdf", when, when);

Try it

Node.js Dates, seconds and strings

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.

Node.js Newer-than checks and what stays fixed

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

NODE
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 a Date.
  • 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 ctime or birthtime. ctime is updated to "now" by the very act of changing the times.
  • Reading a file updates atime on some systems and not on others (noatime and relatime mount options). Do not rely on it as an access log.
  • Writing a file sets mtime again, so apply utimes last.
  • 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 mtimeMs of inputs and outputs is the classic "is it stale" check.