node:dgram

Node.js dgram module, resolvable via both ESM import and CommonJS require. dgram.Socket is an EventEmitter (message-oriented, not a stream), backed by the host's non-blocking UDP transport. Unicast, connected, broadcast, and multicast sends are supported over IPv4 and IPv6.

javascript

import dgram from "node:dgram";
// or: const dgram = require("node:dgram");

const server = dgram.createSocket("udp4");
server.on("message", (msg, rinfo) => {
  console.log(`got ${msg} from ${rinfo.address}:${rinfo.port}`);
});
server.bind(41234, () => {
  const client = dgram.createSocket("udp4");
  client.send("ping", 41234, "127.0.0.1", () => client.close());
});

`dgram.createSocket(type | options[, messageListener])`

type is "udp4" or "udp6". The options form accepts:

Option	Description
`type`	`"udp4"` or `"udp6"` (required).
`reuseAddr` / `reusePort`	Address/port reuse at bind time.
`recvBufferSize` / `sendBufferSize`	Initial kernel buffer sizes.
`signal`	An `AbortSignal`; aborting closes the socket.
`receiveBlockList` / `sendBlockList`	A `net.BlockList`; blocked inbound datagrams are dropped, blocked outbound sends fail with `ERR_IP_BLOCKED`.
`lookup`	Custom resolver used for `send` and `bind` hostnames.

`dgram.Socket`

Binding and sending

bind([port][, address][, callback]) / bind(options[, callback]) — explicit bind; sockets also bind implicitly on the first send or connect.
send(msg[, offset, length][, port][, address][, callback]) — accepts a Buffer, string, TypedArray, or an array of buffers; the connected form omits port / address.
connect(port[, address][, callback]) / disconnect() — fix a default remote for send, with ERR_SOCKET_DGRAM_IS_CONNECTED / ERR_SOCKET_DGRAM_NOT_CONNECTED errors on misuse.
close([callback]), address(), remoteAddress(), ref() / unref().

Socket options

setBroadcast(flag), setTTL(ttl), setMulticastTTL(ttl), setMulticastInterface(iface), setMulticastLoopback(flag), addMembership(group[, iface]) / dropMembership(group[, iface]), the source-specific variants addSourceSpecificMembership / dropSourceSpecificMembership, getRecvBufferSize() / setRecvBufferSize(n), getSendBufferSize() / setSendBufferSize(n), getSendQueueSize(), and getSendQueueCount().

Events

'message' (with (msg, rinfo) where rinfo carries address, family, port, and size), 'listening', 'connect', 'close', and 'error' (e.g. EADDRINUSE, ERR_SOCKET_DGRAM_BAD_PORT).

Multicast

Multicast is supported for both address families: join and leave groups with addMembership / dropMembership (optionally source-specific), and control delivery with setMulticastTTL, setMulticastInterface, and setMulticastLoopback.

javascript

const socket = dgram.createSocket({ type: "udp4", reuseAddr: true });
socket.bind(5007, () => {
  socket.addMembership("239.255.0.1");
});
socket.on("message", (msg) => console.log("multicast:", msg.toString()));

Sandboxing

UDP shares the network sandbox with node:net: the --allow-net / --deny-net flags gate bind, send, and connect.

Notes

Buffer-size and queue introspection are best-effort where the host JDK does not expose the corresponding socket option; values fall back to sensible defaults rather than throwing.
rinfo.family and net.BlockList type arguments are matched case-insensitively ("ipv4" / "IPv4"), as in Node.