Table of Contents

• Path

  • Windows vs. POSIX
  • path.basename(path[, ext])
  • path.delimiter
  • path.dirname(path)
  • path.extname(path)
  • path.format(pathObject)
  • path.isAbsolute(path)
  • path.join([...paths])
  • path.normalize(path)
  • path.parse(path)
  • path.posix
  • path.relative(from, to)
  • path.resolve([...paths])
  • path.sep
  • path.toNamespacedPath(path)
  • path.win32

Path#

The path module provides utilities for working with file and directory paths. It can be accessed using:

const path = require('path');

Windows vs. POSIX#

The default operation of the 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 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'

On Windows:

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

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'

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'

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[, ext])#

• path <string>
• ext <string> An optional file extension
• Returns: <string>

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

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

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

A TypeError is thrown if path is not a string or if ext 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']

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\\']

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'

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 the first character of the basename of path (see path.basename()) is ., then 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: ''

A TypeError is thrown if path is not a string.

path.format(pathObject)#

• pathObject <Object>

  • 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'

On Windows:

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

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

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

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 {}'

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

path.normalize(path)#

• path <string>
• Returns: <string>

The path.normalize() method normalizes the given path, resolving '..' and '.' segments.

When multiple, sequential path segment separation characters are found (e.g. / on POSIX and either \ or / on Windows), they are replaced by a single instance of the platform-specific path segment separator (/ on POSIX and \ on Windows). Trailing separators are preserved.

If the path is a zero-length string, '.' is returned, representing the current working directory.

For example, on POSIX:

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

On Windows:

path.normalize('C:\\temp\\\\foo\\bar\\..\\');
// Returns: 'C:\\temp\\foo\\'

Since Windows recognizes multiple path separators, both separators will be replaced by instances of the Windows preferred separator (\):

path.win32.normalize('C:////temp\\\\/\\/\\/foo/bar');
// Returns: 'C:\\temp\\foo\\bar'

A TypeError is thrown if path is not a string.

path.parse(path)#

• path <string>
• Returns: <Object>

The path.parse() method returns an object whose properties represent significant elements of the path. Trailing directory separators are ignored, see path.sep.

The returned object will have the following properties:

• dir <string>
• root <string>
• base <string>
• name <string>
• ext <string>

For example, on POSIX:

path.parse('/home/user/dir/file.txt');
// Returns:
// { root: '/',
//   dir: '/home/user/dir',
//   base: 'file.txt',
//   ext: '.txt',
//   name: 'file' }

┌─────────────────────┬────────────┐
│          dir        │    base    │
├──────┬              ├──────┬─────┤
│ root │              │ name │ ext │
"  /    home/user/dir / file  .txt "
└──────┴──────────────┴──────┴─────┘
(All spaces in the "" line should be ignored. They are purely for formatting.)

On Windows:

path.parse('C:\\path\\dir\\file.txt');
// Returns:
// { root: 'C:\\',
//   dir: 'C:\\path\\dir',
//   base: 'file.txt',
//   ext: '.txt',
//   name: 'file' }

┌─────────────────────┬────────────┐
│          dir        │    base    │
├──────┬              ├──────┬─────┤
│ root │              │ name │ ext │
" C:\      path\dir   \ file  .txt "
└──────┴──────────────┴──────┴─────┘
(All spaces in the "" line should be ignored. They are purely for formatting.)

A TypeError is thrown if path is not a string.

path.posix#

• <Object>

The path.posix property provides access to POSIX specific implementations of the path methods.

path.relative(from, to)#

• from <string>
• to <string>
• Returns: <string>

The path.relative() method returns the relative path from from to to based on the current working directory. If from and to each resolve to the same path (after calling