Developer Headaches on macOS Catalina: Xcode, Homebrew, Gems

Dirk Avery
Oct 23, 2019 · 6 min read

If you’re a developer and you’ve upgraded to macOS Catalina Version 10.15, chances are you have or will see some errors. Below we’ll look at examples of errors and some common fixes!

A frustrated woman sits in front of a Macbook
A frustrated woman sits in front of a Macbook
(Photo credit: energepic)

Setting up your Mac for development for the first time? See my article Zero to Hero: Set Up Your Mac for Software Development.

Errors and problems

After upgrading to Catalina, I’ve run into three types of issues: Xcode, Homebrew, and Ruby/Gems-related. If you use Xcode, I recommend fixing Xcode first. Many developer tools on Macs rely on Xcode behind the scenes.

While these issues will mostly affect developers, the fixes might help others as well.

Xcode Errors

With the Catalina upgrade, my Xcode did not automatically update to 11.1. The App Store kept trying to update Xcode each night through automatic updates. On its own, it never succeeded. Once it reported it could not download Xcode:

Most of the time, my Mac simply reported failure:

When I tried to run a tool that relies on Xcode, the Mac gave this xcrun error:

Xcode Fixes

The type of Xcode fix you’ll need depends on the answer to one big question: do you use full Xcode? Most developers will probably have the whole enchilada. You can check by going to Finder, then Applications, and look for “” If you see that, you’re using full Xcode.

Xcode Command-Line Tools (not full Xcode)

If you’re just using the Xcode command-line tools (less than 200 MB) versus full Xcode (about 16 gigabytes when extracted), you can save a lot of download time.

To fix Xcode command-line tools, also known as xcode-select, but not Xcode — it’s confusing I know — try this command:

If that doesn’t fix the issue, restart and try a reset:


Most developers will need all of Xcode. The best way to fix Xcode is to download and install Xcode yourself rather than relying on the App Store or automatic updates. Prepare yourself because you’re going to need nearly 30 GB of free space, an Apple Developer account, and a fast connection to download over 7 GB.

This is the process to fix/upgrade Xcode:

  1. Go to the Apple Developer site and login
  2. From the More Software section, click on Xcode 11.4 (or 11.5 when it comes out) and download the Xcode 11.1.xip file. You are fine to save it to the Downloads folder.
  3. Once the XIP is downloaded, double click to begin extracting Xcode. Follow the prompts and accept the terms (assuming that in fact that you, of your own free will, and on the advice of counsel, do accept the terms).
  4. Once extracted, drag the to the Applications folder (often shown under Favorites). When asked, answer that you want to replace the existing and older Xcode.

Once you complete this process, your App Store should soon stop being a politician — begging to perform a task it can’t complete.

Homebrew errors

Homebrew (“Brew”) per se did not have issues after the Catalina upgrade. However, some packages delivered through formulae and casks have not been updated for Catalina and are stuck back in Mojave (or High Sierra, eek!). Old packages will likely have issues with Catalina since a lot has changed.

For example, Catalina now uses Ruby 2.6. Any packages expecting to find Ruby 2.3 are going to have problems. Most have been updated now. However, just after Catalina came out, many formulas (i.e., formulae), like the Travis CI CLI Brew package, hadn’t been updated for Catalina and were still looking for Ruby 2.3.

Homebrew fixes

I’ve seen reports suggesting that problem packages can be fixed through a package reinstall. While this did not fix any specific issues that I had, the procedure ran fine and will hopefully prevent problems.

Reinstalling fixes issues such as when a package has incorrect pre-Catalina configuration or the Catalina version of a package has not yet been installed. Reinstalling should preserve user package settings unlike uninstalling and installing again. Reinstalling a package will not fix anything if there is no Catalina-specific formula.

To reinstall a single package, run this command:

However, if you prefer to take an elephant gun to a squirrel hunt, like me — note that I’m not condoning the harming of animals — you can preemptively reinstall everything! Depending on how many formulae you have, and your connection speed, this might take a minute.

Gem errors

Even if you’re not a Ruby developer, a lot of general development tools are written in Ruby and so the Ruby-version change in Catalina might still affect you. Similar to Homebrew, any pre-Catalina Gems you have lying around will probably be boogered up now.

Like Python, macOS includes a system Ruby that cannot (i.e., should not) be messed up. Catalina includes two significant Ruby changes:

  1. The system Ruby version was upgraded from 2.3 to 2.6, and
  2. The /Library/Ruby directory used by macOS is no longer writable — it is not a place for installing user gems.

If you are calling the macOS system Ruby and try to install a gem under /Library on Catalina, you’ll receive this error:

Gem fixes

There are probably many ways to fix the Catalina-related gem problems. Here I present one good solution that’s suitable to most situations.

As with Python, don’t use the system Ruby for development. Install Ruby and maintain a separate user Ruby and user gems.

Here is the procedure to setup a separate, non-system, user Ruby:

  1. Take note of pre-Catalina gems to make reinstalling them easier:
    $ gem list
  2. Use Homebrew to install Ruby after upgrading to Catalina — Ruby will be “keg only,” meaning it is not symlinked to /usr/local so it won’t interfere with the system Ruby but you’ll need to modify your path:
    $ brew install ruby
    If you were already using Homebrew for Ruby, reinstall Ruby:
    $ brew reinstall ruby
  3. Add the user/Homebrew Ruby to your path first to avoid the system Ruby. For example, if you use Bash, modify your ~/.bash_profile with the following path:
    export RUBY_HOME=/usr/local/opt/ruby/bin
    export PATH=$RUBY_HOME:$PATH
  4. Add the new user gems binary directory to your path. For example, add the following to your ~/.bash_profile (note, GEM_PATH can include multiple paths where Gem will look for Gems whilst GEM_HOME is a single directory that is the default location for Gems — here I just use one directory for both):
    export GEM_PATH=/usr/local/opt/ruby/lib/ruby/gems/2.7.0
    export GEM_HOME=$GEM_PATH
    export PATH=$RUBY_HOME:$GEM_HOME/bin:$PATH
  5. When you want to install a gem, use the --user-install option. For example, this will install the Travis CI CLI gem:
    $ gem install travis --user-install
Image for post
Image for post

Follow us on Twitter 🐦 and Facebook 👥 and join our Facebook Group 💬.

To join our community Slack 🗣️ and read our weekly Faun topics 🗞️, click here⬇

Image for post
Image for post

If this post was helpful, please click the clap 👏 button below a few times to show your support for the author! ⬇


The Must-Read Publication for Creative Developers & DevOps Enthusiasts

Sign up for FAUN


Medium’s largest and most followed independent DevOps publication. Join thousands of aspiring developers and DevOps enthusiasts Take a look.

By signing up, you will create a Medium account if you don’t already have one. Review our Privacy Policy for more information about our privacy practices.

Check your inbox
Medium sent you an email at to complete your subscription.

Dirk Avery

Written by

Cloud engineer, AI buff, patent attorney, fan of cronuts. AWS Certified Solutions Architect — Professional. Go, Python, automation.



The Must-Read Publication for Creative Developers & DevOps Enthusiasts. Medium’s largest DevOps publication.

Dirk Avery

Written by

Cloud engineer, AI buff, patent attorney, fan of cronuts. AWS Certified Solutions Architect — Professional. Go, Python, automation.



The Must-Read Publication for Creative Developers & DevOps Enthusiasts. Medium’s largest DevOps publication.

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store