Node.js Reference ยท HTTP, HTTPS, net, TLS, dgram and dns
Unix domain sockets and named pipes in Node.js
How to use Unix domain sockets and Windows named pipes with Node.js net and http: listening on a path, connecting, cleanup of stale files, permissions and limits.
A Unix domain socket is a way for two processes on the same machine to talk using the socket API, but addressed by a file system path instead of an IP address and port. Windows has the equivalent in named pipes, whose names look like \\.\pipe\my-app. In Node.js both are used through the same net module: pass a path instead of a port, and everything else (streams, events, servers) works as for TCP.
Local sockets skip the network stack, so they are faster than loopback TCP, and they are protected by file permissions instead of being reachable by every local user through a port. Databases (PostgreSQL, Redis), Docker, and many process managers expose them for exactly these reasons.
import net from 'node:net'; net.createServer((socket) => socket.end('hi')).listen('/tmp/app.sock'); net.createConnection('/tmp/app.sock');
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 it works
Addresses. On Linux and macOS the path is a file system entry of type "socket". On Windows, only names that start with \\.\pipe\ or \\?\pipe\ are valid. Linux also supports "abstract" sockets whose name starts with a zero byte ('\0name'); they have no file and vanish when the last process closes them.
Life cycle. server.listen(path) creates the socket file. Closing the server removes it again. If the process crashes, the file stays behind, and the next listen() fails with EADDRINUSE even though nobody is listening. A common start-up routine is to unlink() the old path (ignoring ENOENT) before listening, but only if you know no other live process uses it.
Options. listen({ path, readableAll: true, writableAll: true }) makes the socket file readable and writable for all users. By default, access follows your process umask, so the owner can connect and others may be blocked by the directory permissions.
Limits. The path length is limited by the operating system: about 107 bytes on Linux and about 103 on macOS. Place sockets in a short directory such as /tmp or $XDG_RUNTIME_DIR rather than deep in a project tree.
Addresses of peers. Sockets accepted on a path have no IP: remoteAddress and remotePort are undefined.
Usage notes
- Same API as TCP.
net.createConnection(path),socket.write(),pipeline()andserver.close()behave exactly as innet.createConnection()andnet.Server. - HTTP clients.
http.request({ socketPath })andundiciwith asocketPathdispatcher talk to local daemons such as Docker. - Process communication. For parent and child processes,
child_processIPC channels andprocess.send()are often simpler; use sockets between unrelated processes. - Security. Put the socket in a directory only your user can read. Anyone who can open the file can talk to the server.
- Cross-platform code. Build the path with
process.platform === 'win32' ? '\\\\.\\pipe\\name' : path.join(dir, 'name.sock'). - Cleanup. Remove the socket file on
SIGINTandSIGTERMhandlers, otherwise restarts hitEADDRINUSE.