Node.js v21.7.3 documentation

Windows vs. POSIX#

The default operation of the node:path module varies based on the operating system on which a Node.js application is running. Specifically, when running on a Windows operating system, the node:path module will assume that Windows-style paths are being used.

So using path.basename() might yield different results on POSIX and Windows:

On POSIX:

path.basename('C:\\temp\\myfile.html');
// Returns: 'C:\\temp\\myfile.html' copy

On Windows:

path.basename('C:\\temp\\myfile.html');
// Returns: 'myfile.html' copy

To achieve consistent results when working with Windows file paths on any operating system, use path.win32:

On POSIX and Windows:

path.win32.basename('C:\\temp\\myfile.html');
// Returns: 'myfile.html' copy

To achieve consistent results when working with POSIX file paths on any operating system, use path.posix:

On POSIX and Windows:

path.posix.basename('/tmp/myfile.html');
// Returns: 'myfile.html' copy

On Windows Node.js follows the concept of per-drive working directory. This behavior can be observed when using a drive path without a backslash. For example, path.resolve('C:\\') can potentially return a different result than path.resolve('C:'). For more information, see this MSDN page.

path.basename(path[, suffix])#

• path <string>
• suffix <string> An optional suffix to remove
• Returns: <string>

The path.basename() method returns the last portion of a path, similar to the Unix basename command. Trailing directory separators are ignored.

path.basename('/foo/bar/baz/asdf/quux.html');
// Returns: 'quux.html'

path.basename('/foo/bar/baz/asdf/quux.html', '.html');
// Returns: 'quux' copy

Although Windows usually treats file names, including file extensions, in a case-insensitive manner, this function does not. For example, C:\\foo.html and C:\\foo.HTML refer to the same file, but basename treats the extension as a case-sensitive string:

path.win32.basename('C:\\foo.html', '.html');
// Returns: 'foo'

path.win32.basename('C:\\foo.HTML', '.html');
// Returns: 'foo.HTML' copy

A TypeError is thrown if path is not a string or if suffix is given and is not a string.

path.delimiter#

• <string>

Provides the platform-specific path delimiter:

• ; for Windows
• : for POSIX

For example, on POSIX:

console.log(process.env.PATH);
// Prints: '/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin'

process.env.PATH.split(path.delimiter);
// Returns: ['/usr/bin', '/bin', '/usr/sbin', '/sbin', '/usr/local/bin'] copy

On Windows:

console.log(process.env.PATH);
// Prints: 'C:\Windows\system32;C:\Windows;C:\Program Files\node\'

process.env.PATH.split(path.delimiter);
// Returns ['C:\\Windows\\system32', 'C:\\Windows', 'C:\\Program Files\\node\\'] copy

path.dirname(path)#

• path <string>
• Returns: <string>

The path.dirname() method returns the directory name of a path, similar to the Unix dirname command. Trailing directory separators are ignored, see path.sep.

path.dirname('/foo/bar/baz/asdf/quux');
// Returns: '/foo/bar/baz/asdf' copy

A TypeError is thrown if path is not a string.

path.extname(path)#

• path <string>
• Returns: <string>

The path.extname() method returns the extension of the path, from the last occurrence of the . (period) character to end of string in the last portion of the path. If there is no . in the last portion of the path, or if there are no . characters other than the first character of the basename of path (see path.basename()) , an empty string is returned.

path.extname('index.html');
// Returns: '.html'

path.extname('index.coffee.md');
// Returns: '.md'

path.extname('index.');
// Returns: '.'

path.extname('index');
// Returns: ''

path.extname('.index');
// Returns: ''

path.extname('.index.md');
// Returns: '.md' copy

A TypeError is thrown if path is not a string.

path.format(pathObject)#

• pathObject <Object> Any JavaScript object having the following properties:
  • dir <string>
  • root <string>
  • base <string>
  • name <string>
  • ext <string>
• Returns: <string>

The path.format() method returns a path string from an object. This is the opposite of path.parse().

When providing properties to the pathObject remember that there are combinations where one property has priority over another:

• pathObject.root is ignored if pathObject.dir is provided
• pathObject.ext and pathObject.name are ignored if pathObject.base exists

For example, on POSIX:

// If `dir`, `root` and `base` are provided,
// `${dir}${path.sep}${base}`
// will be returned. `root` is ignored.
path.format({
  root: '/ignored',
  dir: '/home/user/dir',
  base: 'file.txt',
});
// Returns: '/home/user/dir/file.txt'

// `root` will be used if `dir` is not specified.
// If only `root` is provided or `dir` is equal to `root` then the
// platform separator will not be included. `ext` will be ignored.
path.format({
  root: '/',
  base: 'file.txt',
  ext: 'ignored',
});
// Returns: '/file.txt'

// `name` + `ext` will be used if `base` is not specified.
path.format({
  root: '/',
  name: 'file',
  ext: '.txt',
});
// Returns: '/file.txt'

// The dot will be added if it is not specified in `ext`.
path.format({
  root: '/',
  name: 'file',
  ext: 'txt',
});
// Returns: '/file.txt' copy

On Windows:

path.format({
  dir: 'C:\\path\\dir',
  base: 'file.txt',
});
// Returns: 'C:\\path\\dir\\file.txt' copy

path.isAbsolute(path)#

• path <string>
• Returns: <boolean>

The path.isAbsolute() method determines if path is an absolute path.

If the given path is a zero-length string, false will be returned.

For example, on POSIX:

path.isAbsolute('/foo/bar'); // true
path.isAbsolute('/baz/..');  // true
path.isAbsolute('qux/');     // false
path.isAbsolute('.');        // false copy

On Windows:

path.isAbsolute('//server');    // true
path.isAbsolute('\\\\server');  // true
path.isAbsolute('C:/foo/..');   // true
path.isAbsolute('C:\\foo\\..'); // true
path.isAbsolute('bar\\baz');    // false
path.isAbsolute('bar/baz');     // false
path.isAbsolute('.');           // false copy

A TypeError is thrown if path is not a string.

path.join([...paths])#

• ...paths <string> A sequence of path segments
• Returns: <string>

The path.join() method joins all given path segments together using the platform-specific separator as a delimiter, then normalizes the resulting path.

Zero-length path segments are ignored. If the joined path string is a zero-length string then '.' will be returned, representing the current working directory.

path.join('/foo', 'bar', 'baz/asdf', 'quux', '..');
// Returns: '/foo/bar/baz/asdf'

path.join('foo', {}, 'bar');
// Throws 'TypeError: Path must be a string. Received {}' copy

A TypeError is thrown if any of the path segments is not a string.