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.
import fs from "node:fs"; fs.chownSync("/srv/app/uploads", 1001, 1001);
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.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"throwsERR_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 withfs.chmod(). - Not recursive. To change a whole tree, walk it with
fs.readdir()and calllchownon each entry (uselchownso 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()andprocess.getgid()are missing on Windows; guard the call withtypeof process.getuid === "function".- Containers: inside a container root is often a mapped user, so a
chownthat works on your laptop may fail withEPERMon a bind mount.