Complete Guide to Uninstalling Node.js Installed via PKG on macOS

How PKG Packages Work in macOS

In macOS systems, PKG packages are a common software distribution format. When users install Node.js via a PKG file, the installer creates multiple files and directories across the system and generates corresponding installation records. These records are stored in the /var/db/receipts/ directory, which includes a crucial BOM file.

The BOM file, short for Bill of Materials, provides a detailed list of all files created during installation and their locations in the system. For Node.js PKG installations, the BOM file is typically named org.nodejs.pkg.bom or org.nodejs.node.pkg.bom. This file serves as the core reference during uninstallation, as it contains the complete installation manifest.

Exact Uninstallation Method Based on BOM Files

To thoroughly uninstall Node.js installed via PKG, the most reliable approach is to use the BOM file as a guide. The following is a verified uninstallation script:

lsbom -f -l -s -pf /var/db/receipts/org.nodejs.pkg.bom \
| while read i; do
  sudo rm /usr/local/${i}
done
sudo rm -rf /usr/local/lib/node \
     /usr/local/lib/node_modules \
     /var/db/receipts/org.nodejs.*

This script works as follows: first, it uses the lsbom command to read the contents of the BOM file, with parameters specifying output format, long listing mode, simple output, and file paths. The output is then piped to a while loop that reads each file path line by line and uses sudo rm to delete the corresponding file.

It is important to note that the BOM file name may vary depending on the Node.js version or installation method. In some cases, the file might be named org.nodejs.node.pkg.bom. If the original file name does not locate the BOM file, modify the script accordingly.

Additional Uninstallation Steps and Considerations

Beyond the BOM-based method, additional cleanup steps can ensure complete removal of Node.js. Based on user experiences, the following directories and files may contain residual components:

sudo rm -rf /usr/local/include/node /Users/$USER/.npm
sudo rm /usr/local/bin/node
sudo rm /usr/local/share/man/man1/node.1
sudo rm /usr/local/lib/dtrace/node.d

These commands remove Node.js header files, user-level npm cache, executable files, manual pages, and DTrace probes, respectively. Executing them helps clean up potential residual files in the system.

An alternative, simplified uninstallation method involves directly deleting Node.js's main installation directories:

sudo rm -rf /usr/local/{bin/{node,npm},lib/node_modules/npm,lib/node,share/man/*/node.*}

While this method is less precise than the BOM-based approach, it can effectively remove Node.js in many cases. However, it might not clean up all files created by the PKG installer, especially those outside standard directories.

Verification and Reinstallation After Uninstallation

After uninstallation, it is advisable to verify that Node.js has been completely removed. Use the following commands to check:

which node
which npm
node --version
npm --version

If these commands return "command not found" or similar errors, Node.js has been successfully uninstalled. If Node.js or npm is still found, check other installation paths, such as /usr/bin or /opt/local/bin.

If reinstalling Node.js is necessary, consider using package managers like Homebrew, which offer simpler installation and uninstallation processes. For example, after installing Node.js via Homebrew, it can be easily uninstalled with brew uninstall node.

In summary, uninstalling Node.js installed via PKG requires careful handling to ensure all related files are removed. The BOM-based method is the most reliable choice, as it directly references the file list created during installation. Combined with additional cleanup steps, this ensures Node.js is completely removed from the system, preparing it for reinstallation or other operations.