Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท path, os and url

Node.js path.parse() and path.format() methods

Reference for path.parse() and path.format() in Node.js: split a path into root, dir, base, name and ext, change one part and build the path again.

path.parse() splits a path string into an object with five parts: root, dir, base, name and ext. path.format() does the reverse and builds a path string from such an object. Together they let you change one piece of a path, such as the extension, without string slicing.

Both functions only work on text. They never look at the disk.

NODE
import path from "node:path";

path.parse("/srv/app/report.pdf");
// { root: "/", dir: "/srv/app", base: "report.pdf", ext: ".pdf", name: "report" }

Try it

Node.js Parsing different paths

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 Changing a part and formatting

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
path.parse(path): { root: string, dir: string, base: string, ext: string, name: string }
path.format(pathObject): string
Name Description
path The path string to split.
pathObject.root Leading root such as / or C:\. Used only if dir is missing.
pathObject.dir The directory part. Takes priority over root.
pathObject.base The file name with extension. Takes priority over name and ext.
pathObject.name The file name without extension. Used if base is missing.
pathObject.ext The extension, normally with a dot. Used if base is missing.

Returns: parse() returns the five-property object (all strings, possibly empty). format() returns a string.

Errors: ERR_INVALID_ARG_TYPE if path is not a string for parse(), or if the argument of format() is not an object.

Usage notes

  • The pieces fit together. dir + sep + base is the original path (when dir is not empty), and base is name + ext.
  • format() has a priority order. dir wins over root, and base wins over name and ext. When you change ext of a parsed object, you must also drop base, otherwise your change is ignored.
  • A missing dir is allowed. A relative file name such as todo.md parses with dir: "".
  • Dot files and extensions follow path.extname(). .gitignore parses to name: ".gitignore" and ext: "".
  • Trailing separators are dropped. /srv/app/ parses to base: "app", the same as path.basename().
  • format() does not normalize. It joins what you give it, so a messy dir stays messy. Run the result through path.normalize() if needed.
  • Extension without a dot. Current Node versions add the dot when ext does not start with one. Older versions did not, so include the dot to stay portable.
  • Platform rules apply. path.win32.parse("C:\\Users\\ann\\a.txt") gives root: "C:\\".