Node.js Reference ยท path, os and url
Node.js path.posix and path.win32
How Node.js path.posix and path.win32 differ, when path equals one of them, and how to write code that handles Windows and Linux paths on any machine.
The path module is really two modules in one. path.posix implements the rules used by Linux, macOS and URLs: segments are separated by /, and the root is /. path.win32 implements the rules of Windows: both \ and / separate segments, and paths can start with a drive letter (C:\) or a network share (\\server\share).
When you use plain path, Node picks one of the two for you based on the platform that runs the program. That is the right choice when the path refers to files on the current machine. The explicit objects are for the other cases: data that comes from or goes to a different system.
import path from "node:path"; path === path.posix; // true on Linux and macOS path.posix.join("a", "b"); // "a/b" path.win32.join("a", "b"); // "a\\b"
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.
How the two flavours differ
| Topic | path.posix |
path.win32 |
|---|---|---|
Separator (sep) |
/ |
\ |
| Accepted separators in input | / only |
\ and / |
| Root | / |
C:\, \, \\server\share |
PATH list separator (delimiter) |
: |
; |
| Case in comparisons | sensitive | insensitive (for relative, resolve) |
| Output separator | / |
\ |
Every function of the module exists on both objects: join, resolve, normalize, basename, dirname, extname, parse, format, relative, isAbsolute, matchesGlob, plus the sep and delimiter constants.
When to pick one explicitly
- Building URLs or archive paths. Use
path.posix. Web addresses and zip entries always use/, even when your server runs on Windows. - Reading data from another system. A log file or config written on Windows, parsed on Linux, needs
path.win32. Plainpathwould treat the backslashes as part of a file name. - Tests that must behave the same everywhere. Run them against
path.posixandpath.win32explicitly, instead of relying on whichever machine runs the test suite. - File system access. Use the plain, platform-matching
path(or thefsmodule) for real files. The results ofpath.win32on Linux are text only and will not open anything.
Usage notes
- On Windows,
pathispath.win32; everywhere else it ispath.posix. - Neither flavour touches the disk. They only manipulate strings, so you can use both on any machine.
- A backslash is legal in POSIX file names.
path.posix.basename("a\\b")is the whole stringa\b. fileURLToPath()andpathToFileURL()fromnode:urlconvert between paths andfile:URLs and also follow the platform rules.- Do not hard-code separators. Use
path.join()orpath.sepso your code works on both families.