This document specifically refers to upgrades from previous versions of macOS to Catalina (10.15). It should be removed from the source repository when Catalina ceases to be the latest macOS version or when future Catalina versions no longer raise these issues.
Both upgrading to macOS Catalina and running a Software Update in Catalina may cause normal node-gyp
installations to fail. This might manifest as the following error during npm install
:
gyp: No Xcode or CLT version detected!
The newest release of node-gyp
should solve this problem. If you are using node-gyp
directly then you should be able to install v7 and use it as-is.
If you need to use node-gyp
from within npm
(e.g. through npm install
), you will have to install node-gyp
(either globally with -g
or to a predictable location) and tell npm
where the new version is. Either use:
npm config set node_gyp <path to node-gyp>
; or- run
npm
with an environment variable prefix:npm_config_node_gyp=<path to node-gyp> npm install
Where "path to node-gyp" is to the node-gyp
executable which may be a symlink in your global bin directory (e.g. /usr/local/bin/node-gyp
), or a path to the node-gyp
installation directory and the bin/node-gyp.js
file within it (e.g. /usr/local/lib/node_modules/node-gyp/bin/node-gyp.js
).
If you use npm config set
to change your global node_gyp
you are responsible for keeping it up to date and can't rely on npm
to give you a newer version when available. Use npm config delete node_gyp
to unset this configuration option.
Let's first make sure that your Mac is running Catalina:
% sw_vers
ProductName: Mac OS X
ProductVersion: 10.15
BuildVersion: 19A602
If ProductVersion
is less then 10.15
then this document is not for you. Normal install docs for node-gyp
on macOS can be found at https://github.com/nodejs/node-gyp#on-macos
To see if Xcode Command Line Tools
is installed in a way that will work with node-gyp
, run:
curl -sL https://github.com/nodejs/node-gyp/raw/main/macOS_Catalina_acid_test.sh | bash
If test succeeded, you are done! You should be ready to install node-gyp
.
If test failed, there is a problem with your Xcode Command Line Tools installation. Continue to Solutions.
There are three ways to install the Xcode libraries node-gyp
needs on macOS. People running Catalina have had success with some but not others in a way that has been unpredictable.
- With the full Xcode (~7.6 GB download) from the
App Store
app. - With the much smaller Xcode Command Line Tools via
xcode-select --install
- With the much smaller Xcode Command Line Tools via manual download. For people running the latest version of Catalina (10.15.2 at the time of this writing), this has worked when the other two solutions haven't.
xcodebuild -version
should showXcode 11.1
or later.- If not, then install/upgrade Xcode from the App Store app.
- Open the Xcode app and...
- Under Preferences > Locations select the tools if their location is empty.
- Allow Xcode app to do an essential install of the most recent compiler tools.
- Once all installations are complete, quit out of Xcode.
sudo xcodebuild -license accept
# If you agree with the licensing terms.softwareupdate -l
# No listing is a good sign.- If Xcode or Tools upgrades are listed, use "Software Upgrade" to install them.
xcode-select -version
# Should returnxcode-select version 2370
or later.xcode-select -print-path
# Should return/Applications/Xcode.app/Contents/Developer
- Try the acid test steps above to see if your Mac is ready.
- If the acid test does not pass then...
sudo xcode-select --reset
# Enter root password. No output is normal.- Repeat step 7 above. Is the path different this time? Repeat the acid test.
- If the acid test has not succeeded, then try
xcode-select --install
- If the installation command returns
xcode-select: error: command line tools are already installed, use "Software Update" to install updates
, continue to remove and reinstall - Wait until the install process is complete.
softwareupdate -l
# No listing is a good sign.- If Xcode or Tools upgrades are listed, use "Software Update" to install them.
xcode-select -version
# Should returnxcode-select version 2370
or later.xcode-select -print-path
# Should return/Library/Developer/CommandLineTools
- Try the acid test steps above to see if your Mac is ready.
- If the acid test does not pass then...
sudo xcode-select --reset
# Enter root password. No output is normal.- Repeat step 5 above. Is the path different this time? Repeat the acid test.
- Download the appropriate version of the "Command Line Tools for Xcode" for your version of Catalina from https://developer.apple.com/download/more/. As of MacOS 10.15.5, that's Command_Line_Tools_for_Xcode_11.5.dmg
- Install the package.
- Run the acid test steps above.
sudo rm -rf $(xcode-select -print-path)
# Enter root password. No output is normal.sudo rm -rf /Library/Developer/CommandLineTools
# Enter root password.sudo xcode-select --reset
xcode-select --install
- If the acid test steps above still does not pass then...
npm explore npm -g -- npm install node-gyp@latest
npm explore npm -g -- npm explore npm-lifecycle -- npm install node-gyp@latest
- If the acid test still does not pass then...
- Add a comment to nodejs#1927 so we can improve.
Lessons learned from:
- nodejs#1779
- nodejs#1861
- nodejs#1927 and elsewhere
- Thanks to @rrrix for discovering Solution 3