Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท fs and fs/promises

Node.js fs.chown() method

Reference for fs.chown(), lchown() and fchown() in Node.js: change the owner and group by numeric id, leave one unchanged with -1, privileges and Windows.

fs.chown(path, uid, gid, callback) changes who owns a file and which group it belongs to. Both values are numeric ids, not names. Node has no built-in lookup from a user name like www-data to its id; you read ids from process.getuid(), from fs.stat(), or from a command such as id -u.

The call is mostly useful for programs that run as root (installers, deployment tools, containers) and hand files over to a service account. Ordinary users can only "change" ownership to themselves and to groups they belong to.

NODE
import fs from "node:fs";

fs.chownSync("/srv/app/uploads", 1001, 1001);

Try it

Node.js Reading ids and chowning to the same owner

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 Promise form, links and invalid ids

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.chown(path, uid, gid, callback)
fs.chownSync(path, uid, gid): undefined
fsPromises.chown(path, uid, gid): Promise<undefined>

fs.lchown(path, uid, gid, callback)       // acts on the link itself
fs.fchown(fd, uid, gid, callback)         // also filehandle.chown(uid, gid)
Name Description
path A string, Buffer or URL. chown follows symbolic links; lchown does not.
uid New owner id, an integer. -1 leaves the owner as it is.
gid New group id, an integer. -1 leaves the group as it is.

Returns: undefined.

Errors: EPERM if you lack the right to make the change (a non-root user trying to give the file away), ENOENT for a missing path, ERR_INVALID_ARG_TYPE for non-integer ids, ERR_OUT_OF_RANGE for ids below -1 or above the 32-bit limit.

Usage notes

  • Ids, not names. Resolve names yourself. Passing a string such as "root" throws ERR_INVALID_ARG_TYPE.
  • Who may do what: root can set any owner and group. A normal user can only change the group, and only to a group they are a member of; handing a file to another user needs root.
  • The set-user-id and set-group-id bits may be cleared by the system after a successful chown. Set the mode afterwards with fs.chmod().
  • Not recursive. To change a whole tree, walk it with fs.readdir() and call lchown on each entry (use lchown so links do not redirect you outside the tree).
  • Windows: the function is accepted but does nothing useful, because ownership works differently there. Do not depend on it in cross-platform code.
  • process.getuid() and process.getgid() are missing on Windows; guard the call with typeof process.getuid === "function".
  • Containers: inside a container root is often a mapped user, so a chown that works on your laptop may fail with EPERM on a bind mount.