How to Install Node-RED on Windows, Linux and Raspberry Pi

You can install Node-RED in a few minutes on almost any machine, from a Windows laptop to a Raspberry Pi on a factory shelf. This guide walks through each platform, shows how to run Node-RED as a service, secures the editor, and finishes with a working first flow that subscribes to a live MQTT broker so you can see real messages arrive.

What You Need Before You Start

Node-RED is a Node.js application, so the only real prerequisite is a supported Node.js version. Node-RED 4.x requires Node.js 18 or later, and newer releases may raise that minimum, so use the current Node.js LTS release where possible. You also need:

• A user account with permission to install software (administrator on Windows, sudo on Linux).
• Network access to npm (the Node.js package registry) during installation.
• A browser to open the editor at port 1880.

Install Node-RED on Windows

1. Download the Node.js LTS installer (.msi) from nodejs.org and run it with the default options. Accept the option that adds Node.js to your PATH.
2. Open a new PowerShell window and check the versions:

node --version
npm --version

3. Install Node-RED globally:

npm install -g --unsafe-perm node-red

4. Start it:

node-red

The log ends with a line like Server now running at http://127.0.0.1:1880/. Open that address in your browser and the editor appears. Your flows and settings are stored in C:\Users\<you>\.node-red.

To keep Node-RED running after you close the terminal and start it at boot, a common approach is PM2:

npm install -g pm2
pm2 start "$env:APPDATA\npm\node_modules\node-red\red.js" --name node-red
pm2 save

On Windows, PM2 needs an extra helper such as pm2-installer or a Windows service wrapper to start at boot; follow its instructions or use Task Scheduler to run pm2 resurrect at logon.

Install Node-RED on Linux and Raspberry Pi

On Debian, Ubuntu and Raspberry Pi OS, the Node-RED project provides an install script that installs a suitable Node.js version, installs Node-RED, and sets up a systemd service. Run it as a normal user with sudo rights, not as root:

bash <(curl -sL https://github.com/node-red/linux-installers/releases/latest/download/update-nodejs-and-nodered-deb)

The script asks a few questions, including whether to replace an existing Node.js installation and whether to install Pi-specific nodes. When it finishes, start Node-RED and enable it at boot:

node-red-start                      # starts the service and tails the log
sudo systemctl enable nodered.service

Useful commands afterwards:

node-red-stop
node-red-restart
node-red-log

Then browse to http://<device-ip>:1880. To find the Pi's address, run hostname -I. The same script is the easiest way to upgrade later: run it again and it updates Node.js and Node-RED in place. Full details and options are in the official Node-RED getting started docs.

On other distributions, install Node.js LTS from your package manager or NodeSource and run sudo npm install -g --unsafe-perm node-red, then create your own systemd unit.

Install Node-RED With Docker

If you already use containers, Docker is the cleanest option because upgrades and rollbacks are just image tags:

docker volume create node_red_data
docker run -d --name nodered --restart unless-stopped \
  -p 1880:1880 -v node_red_data:/data nodered/node-red:latest

The /data volume holds your flows, credentials and installed nodes, so they survive container upgrades. For a pinned version, replace latest with a specific tag. Our Node-RED Docker guide covers Docker Compose, environment variables and backups.

Secure the Editor Before Exposing It

By default the editor has no login. That is fine on 127.0.0.1, but on a Raspberry Pi or server anyone on the network can open port 1880 and run arbitrary code through a Function or Exec node. Before using Node-RED on a shared network:

1. Generate a password hash:

node-red admin hash-pw

2. Edit settings.js in your user directory (~/.node-red/settings.js) and enable adminAuth:

adminAuth: {
    type: "credentials",
    users: [{
        username: "admin",
        password: "PASTE_THE_BCRYPT_HASH_HERE",
        permissions: "*"
    }]
},

3. Set a credentialSecret in the same file so stored credentials are encrypted with a key you control, then restart Node-RED.

For HTTPS, reverse proxies and more hardening, see how to secure Node-RED.

Your First MQTT Flow After You Install Node-RED

Now connect Node-RED to a real broker. The public MQTT test broker at broker.connectmq.com accepts anonymous connections, so you can test without creating an account. Use a unique topic prefix and remember that the public area is visible to everyone.

In the editor, open the menu (top right), choose Import, paste the JSON below, and click Import:

[
  {
    "id": "c0a1b2c3d4e5f601",
    "type": "mqtt-broker",
    "name": "ConnectMQ public",
    "broker": "broker.connectmq.com",
    "port": "1883",
    "clientid": "nodered-first-4d9e",
    "autoConnect": true,
    "usetls": false,
    "protocolVersion": "4",
    "keepalive": "60",
    "cleansession": true,
    "autoUnsubscribe": true
  },
  {
    "id": "c0a1b2c3d4e5f602",
    "type": "inject",
    "name": "Send test reading",
    "props": [{ "p": "payload" }, { "p": "topic", "vt": "str" }],
    "repeat": "",
    "once": false,
    "topic": "connectmq/demo/4d9e/sensor",
    "payload": "{\"temperature\":21.5}",
    "payloadType": "json",
    "x": 160,
    "y": 80,
    "wires": [["c0a1b2c3d4e5f603"]]
  },
  {
    "id": "c0a1b2c3d4e5f603",
    "type": "mqtt out",
    "name": "Publish",
    "topic": "",
    "qos": "0",
    "retain": "false",
    "broker": "c0a1b2c3d4e5f601",
    "x": 380,
    "y": 80,
    "wires": []
  },
  {
    "id": "c0a1b2c3d4e5f604",
    "type": "mqtt in",
    "name": "Subscribe demo topics",
    "topic": "connectmq/demo/4d9e/#",
    "qos": "0",
    "datatype": "auto-detect",
    "broker": "c0a1b2c3d4e5f601",
    "nl": false,
    "rap": true,
    "rh": 0,
    "inputs": 0,
    "x": 180,
    "y": 160,
    "wires": [["c0a1b2c3d4e5f605"]]
  },
  {
    "id": "c0a1b2c3d4e5f605",
    "type": "debug",
    "name": "Show message",
    "active": true,
    "tosidebar": true,
    "console": false,
    "complete": "true",
    "targetType": "full",
    "x": 410,
    "y": 160,
    "wires": []
  }
]

Replace 4d9e with your own random characters in the client ID and both topics, then click Deploy. The MQTT nodes show a green "connected" status. Click the button on the inject node and the debug sidebar shows the full message, with payload already parsed into an object because of the auto-detect setting. You can also publish from another tool, such as mosquitto_pub -h broker.connectmq.com -p 1883 -i cli-4d9e -t connectmq/demo/4d9e/cli -m hello, and watch it arrive.

From here, the Node-RED MQTT tutorial covers topics, QoS, JSON handling and dashboards in depth.

Troubleshooting the Installation

• node-red is not recognized (Windows): close and reopen PowerShell so the updated PATH is loaded, or check that %APPDATA%\npm is on the PATH.
• Port 1880 already in use: another instance is running. Stop it, or start with node-red -p 1881.
• Editor not reachable from another machine: check the firewall, and confirm Node-RED is not bound only to localhost through uiHost in settings.js.
• MQTT nodes stuck on "connecting": check outbound access to port 1883, and make sure the client ID is not empty or used by another client. Our Node-RED MQTT not connecting guide lists more causes.
• Install script fails on an old Pi: very old models with ARMv6 CPUs may not be supported by current Node.js builds; check the installer's output for guidance.

Moving From the Public Broker to Production

The public broker is perfect for a first flow, but production flows need private credentials and encryption. Move to port 8883 with TLS, which is a checkbox and a few fields in the broker config node; our Node-RED MQTT TLS guide walks through it. Running the broker yourself means patching, certificates and capacity planning, which is why many teams pair Node-RED with a hosted MQTT broker. ConnectMQ gives Node-RED a private broker with TLS on 8883, credentials generated in the portal, and a live topic explorer to check what your flows publish. For the bigger picture, see our cloud MQTT broker guide.

Run Your Node-RED Flows on ConnectMQ

Sign up at app.connectmq.com, choose the free Serverless plan with no credit card, create a broker, and paste the generated username, password and client ID into your mqtt-broker config node. Your new Node-RED installation is then connected to a private, encrypted ConnectMQ broker.

Frequently Asked Questions

Which Node.js version do I need for Node-RED?

Node-RED 4.x requires Node.js 18 or later. Use the current Node.js LTS release unless your platform has a specific constraint.

Where does Node-RED store my flows?

In the user directory, by default ~/.node-red on Linux and macOS and C:\Users\<you>\.node-red on Windows, or /data inside the Docker container. Back up this folder, including flows_cred.json.

How do I update Node-RED?

On Debian, Ubuntu and Raspberry Pi OS, re-run the install script. With npm, run npm install -g --unsafe-perm node-red. With Docker, pull a newer image and recreate the container with the same volume.

Can I install Node-RED without internet access?

Yes, but you must pre-download Node.js and the npm packages on another machine and transfer them, or build a Docker image elsewhere and load it. Connecting to a cloud broker later of course needs outbound network access.