Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท fs and fs/promises

Node.js fs.mkdir() method

Reference for fs.mkdir() and fs.mkdirSync() in Node.js: the recursive option, return values, mode and umask, error codes and idempotent directory creation.

fs.mkdir(path, options, callback) creates a directory. By default it creates exactly one level: the parent must already exist, and the call fails if the directory is already there. With { recursive: true } it behaves like mkdir -p: it creates every missing parent and does not complain when the directory already exists.

The recursive form is what most programs want when they need "make sure this folder exists" before writing a file into it. It also changes the return value in a way worth knowing about: it reports the first directory it actually created.

NODE
import fs from "node:fs";

fs.mkdirSync("logs/2025/may", { recursive: true });

Try it

Node.js One level versus recursive

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 Mode, files in the way and promises

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.mkdir(path[, options], callback)   // callback(err, firstCreatedPath)
fs.mkdirSync(path[, options]): string | undefined
fsPromises.mkdir(path[, options]): Promise<string | undefined>

// options: an integer mode, or
{ recursive?: boolean, mode?: number | string }
Name Description
path A string, Buffer or URL.
options.recursive Create missing parents and accept an existing directory. Default false.
options.mode Permission bits for new directories. Default 0o777. On Windows it is ignored.
callback Called with the error and, when recursive is true, the first path created.

Returns: without recursive, undefined. With recursive, the absolute path of the first directory created, or undefined if everything already existed.

Errors: EEXIST if the target exists (non-recursive, or recursive when it is a file), ENOENT if a parent is missing (non-recursive), ENOTDIR if a parent component is a file, EACCES or EPERM without permission.

Usage notes

  • The mode is filtered by the umask. A requested 0o777 usually produces 0o755. Call fs.chmod() afterwards when exact permissions matter.
  • Idempotent setup: use { recursive: true } at startup so repeated runs do not fail. Do not use "check with existsSync, then create"; another process can create it in between.
  • A file with the same name is still an error, even in recursive mode. Distinguish "already a directory" from "something else is there" by checking err.code.
  • The return value is a cleanup hint. Knowing the first created path lets you remove only what you made.
  • Mode applies to every created level in recursive mode, not just the last one.
  • Windows: drive roots cannot be created and reserved names such as CON fail; the mode option has no effect.