path.posix
Provides POSIX-rule implementations of every path method, identical on every platform.
path.posix- Added in Node.js v0.11.15
Return value
<Object>An object exposing the same methods and properties as the `node:path` module, but always applying POSIX rules: `/` as the separator, `:` as the delimiter, and no drive-letter or UNC handling.
Errors
Nothing by itself; individual methods on it throw TypeError (ERR_INVALID_ARG_TYPE) when given a non-string path.
Changelog
- PHP v15.3.0Also exposed as its own module, so require('node:path/posix') returns the same object.
path.posix is the whole path API frozen to POSIX rules. Every method on it behaves the way node:path behaves on Linux and macOS, no matter what operating system the process is actually running on: / separates segments, : separates entries in a PATH-style list, and a backslash is just an ordinary character in a filename.
When to reach for it
Use it whenever the string you are manipulating is not a path on the local disk. URL pathnames, HTTP route patterns, S3 and object-storage keys, tar and zip entry names, and Git paths are all slash-separated by specification. Passing those through the platform default means the same code produces a/b on Linux and a\b on Windows, and the second one is wrong everywhere it is sent.
What trips people up
It is a rule set, not a converter. path.posix.normalize('C:\\a\\b') returns the string unchanged, because under POSIX rules that is a single filename containing backslashes, and path.posix.dirname() on it returns .. To turn a native path into a slash path, split on path.sep first and re-join with path.posix.join().
path.posix.resolve() still falls back to the real process.cwd(), so on Windows it can splice a drive letter into otherwise POSIX output.
Example
When to use it
- Building URL pathnames or API route strings that must use forward slashes on any host OS
- Joining S3/object-storage keys or tar/zip entry names, which are slash-separated by spec
- Converting a native file path into a web path for a static-site or asset manifest
- Parsing a POSIX-style PATH string on a Windows CI runner
Frequently asked questions
How do I always get forward slashes from path.join in Node?
Use path.posix.join() instead of path.join(); it emits / on every platform, including Windows. If your input is a native path that may already contain backslashes, split it on path.sep first and spread the pieces into path.posix.join(), because path.posix will not rewrite backslashes for you.
What is the difference between path and path.posix?
path is an alias for whichever implementation matches the host OS — path.win32 on Windows, path.posix everywhere else — while path.posix is always the POSIX implementation. On Linux and macOS the two behave identically, so bugs from using the wrong one only show up once the code runs on Windows.
Should I use path.posix for URLs?
It is a reasonable fit for joining and normalising URL pathname fragments, since URLs are always slash-separated. It is not a URL parser though: it knows nothing about query strings, hashes, percent-encoding or protocol-relative //host prefixes, so use the WHATWG URL class when those matter.
More examples
Normalising a route built from fragments
The first line prints /api/v2/users/42 — the stray trailing slash, the ./ and the ../ are all collapsed. relative() prints ../../impl/bbb, format() rebuilds /srv/static/app.css from its pieces, and parse() shows the same path taken apart into root, dir, base, ext and name. Every one of these values is byte-identical on a Windows host.
const path = require('node:path');
const routes = ['/api/', 'v2', './users', '../users/42'];
console.log(path.posix.normalize(routes.join('/')));
console.log(path.posix.relative('/data/orandea/test/aaa', '/data/orandea/impl/bbb'));
console.log(path.posix.format({ dir: '/srv/static', name: 'app', ext: '.css' }));
console.log(JSON.stringify(path.posix.parse('/srv/static/app.css')));Turning native file paths into web paths
Prints posix-demo/pages/about.md -> /posix-demo/pages/about, then cleaned up: false. The split on path.sep followed by path.posix.join() is the conversion step: on Windows the local path would contain backslashes, and the URL would still come out with forward slashes. Joining the raw native string with path.posix.join() would not fix it.
const fs = require('node:fs');
const path = require('node:path');
fs.mkdirSync('posix-demo/pages', { recursive: true });
fs.writeFileSync('posix-demo/pages/about.md', '# About\n');
const root = 'posix-demo';
for (const entry of fs.readdirSync(path.join(root, 'pages'))) {
const local = path.join(root, 'pages', entry); // OS separators
const url = '/' + path.posix.join(...local.split(path.sep)); // always slashes
console.log(local, '->', url.replace(/\.md$/, ''));
}
fs.rmSync('posix-demo', { recursive: true, force: true });
console.log('cleaned up:', fs.existsSync('posix-demo'));Reaching it as its own module
The first two lines print true: node:path/posix (added in v15.3.0) is the very same object, and each variant still carries a reference to the other, so path.posix.win32 works. isAbsolute('C:\\temp') prints false because a drive letter means nothing under POSIX rules — only a leading / counts as absolute.
const path = require('node:path');
const posix = require('node:path/posix');
console.log(posix === path.posix);
console.log(posix.win32 === path.win32);
console.log(posix.join('/etc', 'nginx', 'nginx.conf'));
console.log(posix.isAbsolute('C:\\temp'));
Discussion