Node.js Update

Why is it necessary to update this?

ioBroker does not work without Node.js; details can be found under Architecture .
For more information about Node.js, see the Wikipedia article on Node.js.

As is common with many open-source technologies, Node.js is evolving rapidly.
Updates that improve stability and security , or even add new features , are released regularly.

Node.js 22.x is the current recommended version for ioBroker installations. This version has been in Active Long Term Support (LTS) status since October 2024 and will be supported until April 2027. The ioBroker community has officially recommended this version, and the `iob nodejs-update` command automatically installs the recommended version.

Node.js 24.x has also been LTS since October 2025 and will be supported until April 2028. It works, but is not yet the general recommendation: Until all adapters have been tested for it, 22.x remains the safer option.

When switching Node.js versions, certain prerequisites must be checked and corrected beforehand if necessary.
It is important to pay attention to the paths in which the installation is located.

Node.js 18.x has been end-of-life since April 2025 and no longer receives security updates. Node.js 22.x is the recommended LTS version. Administrators using version 8 and later require Node.js 22 anyway.

Recommended update methods

The simplest method for existing ioBroker installations is the integrated update command:

iob nodejs-update

Procedure

1 - Check the circumstances

• Version and path
• operating system
• js-controller
• adapter

2 - Create a backup

Before making any changes to the system, a backup must be created. Depending on the system, there are various options. The BackitUp adapter or a command-line command is recommended. The backup should be recent to minimize data loss.

3 - Update adapter

The adapters used in the system should be compatible with the new Node.js version; they may need to be updated.

4 - Stop ioBroker

ioBroker can be stopped using its own console command or via system service management.

5 - Check if any processes are still running

This usually terminates all processes. However, to be on the safe side, you should double-check that no processes (adapters, backups) are still running. You can also use a tool like "top" to check if any processes still exist that begin with "io.".

6 - Node.js Update

The next step is to update Node.js to the desired new version. However, the update process differs depending on the installed operating system; see the instructions.

The Node Package Manager, or Node Package Manager for shortnpm , is also automatically updated.

7 - Check version and paths

After the update is complete, the paths and installed versions are checked again.

8 - Run ioBroker faster

Since installing Node.js, as mentioned earlier, makes some changes to the system, it is necessary to run the ioBroker fixer afterwards. This restores, among other things, the security settings required for ioBroker to function and checks and corrects all permissions.

9 - Start ioBroker

Some JavaScript modules contain components that need to be compiled. This process occurs during installation. Compiling these modules binds them to the Node.js version. After an update, these components must therefore be recompiled. Since js-controller version 3.0, an attempt is made to detect adapters containing such components and automatically perform a rebuild. This process can take some time, and the affected adapters may restart multiple times. This can be observed in the log file. The easiest way to do this is in a terminal using...iob logs --watch | uniq .

iobroker rebuild

iobroker rebuild --install

iob install serialport

Instructions for Debian/Ubuntu

1 - Check version and path

sudo ln -s /usr/bin/node /usr/bin/nodejs &> /dev/null
type -p nodejs node npm npx corepack && nodejs -v && node -v && npm -v && npx -v && corepack -v

• output

/usr/bin/nodejs
/usr/bin/node
/usr/bin/npm
/usr/bin/npx
/usr/bin/corepack
v22.x.x
v22.x.x
10.x.x
10.x.x
0.x.x

Important: nodejs is located in /usr/bin, node is located in /usr/bin, npm is located in /usr/bin, npx is located in /usr/bin, corepack is located in /usr/bin, and the version numbers of nodejs and node, as well as of npm and npx, are identical.

2 - Backup

iobroker backup

• alternative options

3 - Update adapter

• Instructions can be found under Manage Adapters

iob update

4 - Stop ioBroker

iobroker stop

5 - Check ioBroker processes

ps aux | grep 'io\|PID'

• and

ps aux | grep 'backup\|PID'

• if processes are still ongoing

sudo kill -9 [PROZESS-ID]

Or to terminate all ioBroker processes:

sudo pkill -f iobroker
sudo pkill -f "io\."

6 - Node.JS Update

Method A: ioBroker's own update command (Recommended for 2025)

# Direktes Update auf empfohlene Version (22.x)
iob nodejs-update

# Oder spezifische Version
iob nodejs-update 22

Method B: NodeSource Repository

• Details about Node.js

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

• For other Node.js versions, simply add the following to the URL:22 replace it with the other version number.

As of October 2025, version 22.x of Node.js is recommended for ioBroker!

!> Odd-numbered Node.js versions must not be used.

Node.js 18.x is End-of-Life (since April 2025) and should no longer be used.

7 - Check version/path

type -p nodejs node npm npx corepack && nodejs -v && node -v && npm -v && npx -v && corepack -v

8 - Run iobroker fixer

iobroker fix

9 - Start ioBroker

iobroker start

Instructions for Windows

Node.js is updated by running the Windows Installer.

Recommended steps for Windows (2025):

1. Download the latest Node.js Windows Installer from nodejs.org (version 22.x LTS)
2. Stop ioBroker via services management or command line
3. Run the installer (automatic update)
4. Run ioBroker Fixer:iobroker fix
5. Start ioBroker

Alternative for Windows: Windows Subsystem for Linux (WSL2) with Ubuntu and then follow the Linux instructions.

Docker tutorial

• Node.js is typically updated by updating the container to a new version of the Docker image.
• Detailed instructions and further details about the iobroker container can be found at buanet .

Problem solving

manual rebuild

• There is information on this.

iobroker rebuild

• if that's not enough

iobroker rebuild --install

• Simply execute it manually at the shell. Ideally, this should automate everything.

This command performs a complete reinstallation of all Node modules and should resolve most problems after a Node.js update.

Common problems (2025)

"nodejs is NOT correctly installed"

# Lösung: Fixer ausführen
iobroker fix

# Falls das nicht hilft, Node.js neu installieren
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

NPM error after update

# NPM Cache leeren
npm cache clean --force

# Node modules neu installieren
cd /opt/iobroker
rm -rf node_modules
npm install

Adapters don't work after update

# Einzelne Adapter neu installieren
iob install [ADAPTER-NAME]

# Oder alle Adapter rebuilden
iobroker rebuild --install

Permission problems

# Berechtigungen korrigieren (Linux)
sudo chown -R iobroker:iobroker /opt/iobroker
iobroker fix

Diagnostic commands

# Umfassende Systemdiagnose
iob diag

# Node.js Installation prüfen
which node
which npm
ls -la $(which node)
node -v
npm -v

# ioBroker Status
iob status
iob list instances

As long as the js-controller is lower than version 4, ioBroker must be run more quickly even during a Node.js update within a major version.
With the future js-controller in version 4, rebuilds will be handled fully automatically.