If you search for "install Java on Mac," you'll find a confusing number of vendors, version numbers, and installation methods. To make it easy, I'll cut through the confusion and show you a recommended Java installation path that takes about five minutes.

Here's my recommendation: Install Java 25 using Homebrew with the Eclipse Temurin distribution. Java 25 is the current LTS (Long-Term Support) release and your best choice unless your work team or university course uses an older version. With Homebrew, one terminal command accommodates the entire installation. The Temurin distribution is free, certified, and unencumbered by Oracle's licensing restrictions.

Now I’ll walk you through the process.

Table of Contents

1. What You Need Before You Begin

2. How to Check if Java Is Already Installed

3. Why Eclipse Temurin and Why Not Oracle

4. How to Install Java with Homebrew

5. How to Verify the Installation

6. How to Set JAVA_HOME for Build Tools

7. How to Troubleshoot Common Problems

8. Alternative Installation Methods

9. What's Next

What You Need Before You Begin

With this recommended path, you only need two things before you install Java: a terminal application and the Homebrew package manager.

Terminal

Terminal is the built-in Mac terminal application. If you don’t know, you can learn how to open Terminal here. You'll use it to run the installation commands.

Homebrew

Homebrew is a package manager you can use to install software programs for the command line. Check if you already have it like this:

$ brew --version
Homebrew 5.0.11

If you see a version number, you're ready. If you see zsh: command not found: brew you need to install Homebrew first. Follow the instructions at Install Homebrew.

How to Check if Java Is Already Installed

Run this command to check for an existing Java installation:

$ java -version

You'll see one of two results.

If Java is installed, you'll see output like this:

openjdk version "25.0.1" 2025-10-21 LTS
OpenJDK Runtime Environment Temurin-25.0.1+8 (build 25.0.1+8-LTS)
OpenJDK 64-Bit Server VM Temurin-25.0.1+8 (build 25.0.1+8-LTS, mixed mode)

If the version number shows 25, you already have the latest Java and you can stop here.

If Java is not installed, you'll see a message, "The operation couldn't be completed. Unable to locate a Java Runtime." You'll need to install Java as described below.

If you previously installed Java but see this dialog, something is wrong with your installation. See Unable to Locate a Java Runtime for troubleshooting. For detailed guidance on Java version output, see Check Java Version on Mac.

Why Eclipse Temurin and Why Not Oracle

If you search for Java downloads, you'll encounter several potentially confusing terms. Here's what they mean.

JDK stands for Java Development Kit. It contains the compiler, runtime, and developer tools you need to build and run Java applications. Vendors used to offer a JRE (Java Runtime Environment) for non-developers, but now the JDK does everything.

OpenJDK is the official open-source implementation of Java. All major Java vendors build from this same source code, so the core functionality is identical across vendors.

Eclipse Temurin is the distribution many developers recommend. It comes from the Adoptium project and is backed by IBM, Microsoft, Red Hat, and Google, among others. It's completely free for any use, including commercial production. Temurin is TCK-certified, meaning it passes Oracle's official compatibility tests (over 139,000 of them). You can trust that your Java code will run correctly.

Why not Oracle JDK? Oracle changed its licensing in January 2023. The new model charges per employee across the entire organization, not per Java user. A 500-person company would pay $90,000 per year. Oracle actively audits for compliance.

Temurin is functionally identical to Oracle JDK and is free to use under its open‑source license, avoiding Oracle’s Java subscription fees.

If you deploy to AWS, Amazon Corretto is another good free option. If you need Java 8 for legacy code, Azul Zulu provides well-supported builds. For a comparison of Java distributions, see Install JDK on Mac.

How to Install Java with Homebrew

Homebrew offers two ways to install Java: the cask method and the formula method. The cask method is easier because it installs the vendor's macOS package to the standard system location. Apple's macOS discovers it automatically with no extra configuration.

Run these two commands:

$ brew update
$ brew install --cask temurin@25

The first command refreshes Homebrew's package list. The second downloads and installs Eclipse Temurin JDK 25.

Homebrew places the JDK at /Library/Java/JavaVirtualMachines/temurin-25.jdk/. This is the standard macOS location for Java installations. Apple's macOS includes a Java launcher at /usr/bin/java that automatically searches this directory. You don't need to configure your PATH.

Homebrew also detects your Mac's chip architecture automatically. You'll get the correct native build whether you have an Apple Silicon or Intel Mac.

For more details about the Homebrew installation process, including the alternative formula method and troubleshooting, see Brew Install Java, Cask Method.

How to Verify the Installation

After installation, open a new Terminal window. Existing windows may not detect the new installation.

Check the Java version:

$ java -version
openjdk version "25.0.1" 2025-10-21 LTS
OpenJDK Runtime Environment Temurin-25.0.1+8 (build 25.0.1+8-LTS)
OpenJDK 64-Bit Server VM Temurin-25.0.1+8 (build 25.0.1+8-LTS, mixed mode)

This confirms three things: the version number (25.0.1), the distribution (Temurin), and that the 64-Bit Server VM is active.

Check the compiler:

$ javac -version
javac 25.0.1

List all installed JDKs:

$ /usr/libexec/java_home -V
Matching Java Virtual Machines (1):
    25.0.1 (arm64) "Eclipse Adoptium" - "OpenJDK 25.0.1" /Library/Java/JavaVirtualMachines/temurin-25.jdk/Contents/Home

If all three commands produce the expected output, Java is installed and working.

How to Set JAVA_HOME for Build Tools

For most users, Java works immediately after installation. The java and javac commands are available with no additional setup.

However, some build tools require the JAVA_HOME environment variable. Apache Maven, Gradle, and Android SDK all look for it. If you see errors mentioning "JAVA_HOME is not set," you need this step.

If you only run Java applications or use IntelliJ IDEA (which manages Java paths internally), you can skip this section.

Add this line to your ~/.zprofile file:

export JAVA_HOME=$(/usr/libexec/java_home)

This uses Apple's java_home utility to find the installed JDK automatically. After saving the file, you'll need to run source ~/.zprofile or close and reopen your terminal. Verify it works:

\( echo \)JAVA_HOME
/Library/Java/JavaVirtualMachines/temurin-25.jdk/Contents/Home

For complete configuration instructions, see Set JAVA_HOME on Mac.

How to Troubleshoot Common Problems

"Unable to locate a Java Runtime" message keeps appearing. Run java -version to verify Java is installed. If you just installed Java, see Unable to Locate a Java Runtime.

Wrong Java version appears. You have multiple JDKs installed and macOS selected a different one. Run /usr/libexec/java_home -V to list all installed versions. See Set JAVA_HOME on Mac to point to the version you want.

Alternative Installation Methods

Homebrew is the fastest path, but other options exist.

1. Manual download: You can download the .pkg installer directly from adoptium.net and double-click to install. This is a good choice if you don't use Homebrew. See Install Java on Mac for detailed instructions.

2. Homebrew formula. The command brew install openjdk@25 installs a Homebrew-managed build. This approach requires manual symlink configuration before macOS can discover it. See Brew Install Java, Formula Method for details.

3. Version managers. Tools like SDKMAN and mise can install and switch between multiple Java versions per project. If you work on codebases that require different Java versions, see Java Version Managers.

What's Next

You now have Java 25 installed on your Mac. You've verified it works and configured JAVA_HOME for build tools. You're ready to compile and run Java applications.

If your team or university course requires Java 21 instead, see Install Java 21 on Mac. If you need to remove Java, see Uninstall Java on Mac.

This article is based on my guides that offer additional details about how to install Java on Mac and choose the latest Java version.

Though the final release of macOS Sequoia (macOS 15) won't be available until late September or early October 2024, I'll show you how to install the public beta for an advance look. It's actually stable enough for daily use.

The macOS Sequoia public beta is available to anyone who wants to try it, though you have to register with the Apple Beta Software Program to obtain it.

Table of Contents

1. Is macOS Sequoia stable?
2. Time needed to install
3. What's new in macOS Sequoia
4. Features in macOS Sequoia
5. Small changes in macOS Sequoia
6. Requirements for macOS Sequoia
7. Back up your Mac first
8. Sign up to get the public beta
9. Where to install the macOS beta
   – Install on a spare Mac
   – Install on an external drive
   – Install on a separate volume
10. Use the Startup Manager
11. Halt macOS beta updates
12. Return to macOS Sonoma
13. What's next

Is macOS Sequoia Stable?

So far, users are reporting the beta version has only a few minor issues. They say the beta is "surprisingly stable."

There are reports of issues with external monitors, and users say to expect issues with external third-party devices. There may also be issues with screen sharing, video conferencing (Zoom particularly), or streaming in web browsers.

Time Needed to Install

The update from macOS Sonoma to macOS Sequoia can take more than an hour. The time needed varies widely based on factors such as the size of the update, your Internet speed, and the age and performance of your Mac.

What's New in macOS Sequoia

Users are reporting that macOS Sequoia is faster, with better battery life on laptops, but we can't be sure until we see the final release.

Looking closely at macOS Sequoia, it's plain that it isn't a major overhaul of the operating system. The most useful features are Window Tiling and a new Passwords application, as well as iPhone mirroring and seamless drag and drop between devices.

I've compared Sonoma vs Sequoia in a separate article, and also provided some advice to answer the question, Should You Update to macOS Sequoia?

Features in macOS Sequoia

macOS Sequoia Passwords application

Password Manager

MacOS Sequoia adds a new app called Passwords, improving the way users manage their login credentials.

Built on the existing framework of Apple's Keychain, this app consolidates passwords, passkeys, Wi-Fi passwords, and other essential credentials into one secure, centralized location.

Credentials previously could be edited in System Settings but they were buried and hard to find. The new Passwords app will largely eliminate the need to use third-party password managers such as 1Password, LastPass, or Bitwarden.

macOS Sequoia Window Tiling

Window Tiling

For years, Windows users have complained that MacOS lacks a tiling window manager. MacOS Sequoia adds a new feature called Window Tiling, which allows users to drag windows to the edge of the screen for placement side by side, top and bottom, or in a grid. Third-party utilities have more features but the built-in Window Tiling is a welcome addition.

These two features make an upgrade worthwhile. In addition, Apple has announced other capabilities.

iPhone Mirroring

This feature allows the use of iPhone apps within a macOS window. Users can now check iPhone notifications directly on their Mac, making the Mac an extension of the iPhone.

One user noted, “No longer do I have to find my phone when I am at home sitting in front of my Mac just to check on a notification.”

Seamless Drag and Drop Between Devices

This feature aims to improve the reliability of transferring files between iPhone and Mac, addressing issues with AirDrop. "Transferring files from Mac to an iPhone Apps no longer requires 5+ tedious steps," a user mentioned.

Apple Intelligence

MacOS Sequoia will introduce the first use of Apple Intelligence, Apple's AI initiative. Apple Intelligence comprises new system-level capabilities, leveraging Apple custom silicon for both local and cloud-based processing.

This is more of a future prospect as AI gets baked in to more applications, but we may see improvements to Siri in macOS Sequoia. Note that these capabilities won't be present when you install macOS Sequoia on an Intel-based Mac.

Small Changes in macOS Sequoia

• System Settings: Individual menus have been rearranged for quicker access to frequently used menus.
• Safari: The web browser has faster page load times, a new start page, and a brand new unified menu similar to "compact mode" on iOS. It can summarize websites and highlight relevant information.
• Notes: Minor improvements including collapsible sections and a choice of highlight styles. Also, Notes adds support for live audio transcription and math equations.
• Videoconferencing: Preview what you share in video calls for presentations and screen sharing. Also, background replacements are built into the macOS video feed so you won't need to use background replacements in Zoom or other conferencing apps.

Requirements for macOS Sequoia

Check your macOS version and update macOS to Sonoma (macOS 14) before installing the macOS Sequoia beta.

You should keep the current macOS Sonoma available on your Mac, just in case you run into problems with the beta. That means you should install the macOS Sequoia beta on a separate volume, external drive, or a secondary Mac.

Also, macOS Sequoia does run on older Intel-based Macs, but it may be slow. So I recommend installing it only on Macs with M1, M2, or M3, the Apple Silicon chips.

You can install the macOS Sequoia beta on any computer that runs runs macOS Sonoma with the exception of the 2018–2019 MacBook Air models with Intel Amber Lake chips. Apple provides a list of supported models for macOS Sequoia.

Back Up Your Mac

If you've got a new Mac that hasn't been used, you don't need to back up files. Or, if you're like many developers, you won't need to back up your Mac if you have all your important files stored in the cloud.

Otherwise, if there are important files on your computer, make sure you have a backup of your Mac before you install the macOS beta version.

Sign Up to Get the Public Beta

Apple offers a public beta version as well as developer beta versions. The developer beta is released first and intended for software developers to test compatibility of applications, while the public beta is released a few weeks later. The public beta is more stable and has fewer bugs than the developer beta.

The public beta is available now, for free. Sign up for the public beta on the Apple Beta Software Program website. After you sign up with your Apple ID, your System Settings will show that beta updates are available.

Where to Install the macOS Beta

Your best option is to install the macOS beta on a spare Mac, if you have an extra computer. Ideally, you have a relatively new Mac with an Apple Silicon M1, M2, or M3 chip. If you have an older Mac, you may want to avoid the beta version because it could slow down your computer.

Installing on a spare Mac allows you to try the new macOS version without affecting your daily productivity.

Alternatively, you can install the macOS beta on a separate volume on your Mac. This allows you to boot into the beta version when you want to try it out.

You can also install the beta version on an external drive. In either case, you need to hold the power button until you see the Startup Manager menu which lets you select an alternate to the default startup disk.

Here are instructions for installing the macOS Sequoia beta version on a spare Mac, an external drive, or a separate volume.

Install on a spare Mac

Here's how to install the macOS Sequoia beta on a Mac running macOS Sonoma.

1. Open System Settings and navigate to General and Software Update.
2. Click the "circle I" info button in Beta Updates.
3. Set the Beta Updates to macOS Sequoia Public Beta.
4. Click "Done" and your Mac will check for software updates.
5. After a check, the upgrade name appears with an "Upgrade Now" button.
6. Software updates require at least 20% battery power so you may need to connect to power if your battery is low.
7. Enter your password to start the software update. With a fast Internet connection, the download should take about 30 minutes. After the download, the "preparing" process will take about 15 minutes.
8. Your Mac will restart after the installation. You'll see the Apple logo and a progress bar. The installation process will take about 15 minutes with several automatic restarts.
9. After installation completes, you'll see the login screen. Enter your Mac password, then your Apple ID password, and "Continue" or "Set Up Later" through various agreements and settings.
10. The macOS Sequoia desktop will appear with a the Feedback Assistant application open. Use the Feedback Assistant to report any bugs or issues you encounter.
11. Check About This Mac to confirm you're running macOS 15.

If you don't see macOS Sequoia Public Beta option in Beta Updates, sign up for the Apple Beta Software Program. After you sign up with your Apple ID, your System Settings will show that beta updates are available.

Install on an external drive

Not many users own an external drive now that cloud storage is popular. But if you have an external drive, you can install the macOS beta on it.

You'll need to format the drive so you must erase any files already on the drive. It's best if you own a fast SSD drive with a USB-C or Thunderbolt connection for use of the operating system. You can use a USB thumb drive, but you'll need at least 32 GB of space.

How to format the external drive

1. Connect the external drive to your Mac.
2. Search in Spotlight and open Disk Utility.
3. Select the external drive in the left sidebar.
4. Click Erase to reformat the drive.
5. Name the drive macOS Sequoia or whatever you like.
6. Choose Mac OS Extended (Journaled) as the format.
7. Choose GUID Partition Map as the scheme.
8. Click Erase to format the drive.
9. Close Disk Utility after the drive formatting is done.

How to get the macOS Sequoia beta

You'll need to download *.pkg files to install on an external drive. Several sites provide links to installer *.pkg files for macOS betas. Check:

• betaprofiles.dev
• mrmacintosh.com

Download the latest InstallAssistant.pkg. These files are huge (14GB or more) so a download may take more than 30 minutes with a fast Internet connection.

How to install the macOS Sequoia beta

Double click the InstallAssistant.pkg file to start the installation. Click "Change Install Location" to select the external drive. In the step "Destination Select" you can select the external drive as the installation destination.

Install on a separate volume

If you want to install the macOS beta on a separate volume, follow these steps. You might hear this process called a "dual boot" or "separate partition" installation. Apple's APFS file system introduced "volumes" which are like partitions but more flexible.

You'll have two volumes on your Mac, one for macOS Sonoma and one for macOS Sequoia. You can use the Startup Manager to choose which volume to boot from.

How to create a new volume

1. Search in Spotlight and open Disk Utility.
2. Select the internal drive in the left sidebar.
3. Click the + button in the top bar to add a new volume (or "Edit" > "Add APFS Volume" in the menu).
4. Name the volume macOS Sequoia or whatever you like.
5. Choose a format (commonly "APFS").
6. Click Add to create the volume.
7. Click "Done" and close Disk Utility after the volume creation is done.

Get the macOS Sequoia beta

You'll need to download *.pkg files to install on a separate volume. Several sites provide links to installer *.pkg files for macOS betas. Check:

• betaprofiles.dev
• mrmacintosh.com

Download the latest InstallAssistant.pkg. These files are huge (14GB or more) so a download may take more than 30 minutes with a fast Internet connection.

Install the macOS Sequoia beta

Double click the InstallAssistant.pkg file to start the installation. Click "Change Install Location" to select the volume you created. In the step "Destination Select" you can select the new volume as the installation destination.

Use the Startup Manager

Hold down the power button when starting your Mac to enter the Startup Manager. "Loading startup options" will appear. You have a choice of booting from the internal drive, an external drive (if connected), a disk volume, or "Options."

Select the external drive or volume to boot from. You can set a default for the external drive or volume in System Settings > Startup Disk.

Halt macOS Beta Updates

If you don't want to continue using macOS Sequoia beta, you can turn off beta updates.

Go to System Settings > General > Software Update. Click the "circle I" info button in Beta Updates and set the Beta Updates to Off. This will stop the macOS beta updates.

This is a necessary step if you don't want to use the macOS beta. If you don't do this, your Mac will continue to update to the latest beta version.

Return to macOS Sonoma

If you're using an external drive or separate volume to run the macOS beta, you still have macOS Sonoma on your Mac as the primary volume on the internal drive. Reformat the external drive or delete the volume if you no longer want to use the macOS beta.

Restore macOS Sonoma on a Spare Mac

If you are using macOS Sequoia on a spare Mac, you can restore macOS Sonoma by reinstalling it.

You can download and install macOS Sonoma from the Mac App Store. Search in the Mac App Store for "macOS Sonoma" or use this link to view the listing for macOS Sonoma. Click "Get" and the App Store will open System Settings > General > Software Update and begin downloading macOS Sonoma.

Downloads from the App Store are slow, so expect a wait of an hour or more. The App Store installs an application Install macOS Sonoma in the Applications folder.

After the download is complete, the Install macOS Sonoma application will launch automatically. Follow the instructions to install macOS Sonoma.

Alternatively, you can directly download an installer *.pkg file to restore macOS Sonoma. The download is faster than the App Store. Check:

• mrmacintosh.com

Double click the InstallAssistant.pkg file to start the installation.

What's Next

After you've installed macOS Sequoia, I've got recommendations for a Mac setup, including Mac name settings, Dock settings, and Finder settings.

For developing software on the Mac, you'll need to:

• Install Xcode Command Line Tools for missing command line tools
• Install Homebrew as a software package manager
• Install Git for version control

When you update macOS, you may also want to install newer software as well. Here are new and recommended applications for macOS Sequoia:

• Terminal alternatives
• Text Editor options
• ChatGPT desktop application for better ChatGPT usability

Conclusion

After October 2024, you'll need to update macOS from Sonoma to Sequoia to stay up to date with bug fixes, security, and software compatibility, especially if you are a software developer.

Before then, you can try out the macOS Sequoia beta to see what's new and provide feedback to Apple. See an article MacOS Beta for more details.

Though macOS Sequoia doesn't bring spectacular changes, new features like Window Tiling and the Passwords app are useful.

Installing the macOS beta takes an hour or more, but you may find it is stable enough for daily use, giving you access to new features now.

I recently wrote an article for freeCodeCamp titled "How to Install Python on a Mac", which provides a clear guide to installing Python on macOS.

As a follow-up, I will discuss errors you may encounter when installing Python on macOS and how to fix them in this article.

Contents

Here's what we'll cover here:

• How to Fix the "command not found: python" Error
• Using an Out-of-date Python
• Using the System Python
• Using the Homebrew Python
• Missing Pip
• Pip Package Installation Errors
• More on Mac Python
• Conclusion

How to Fix the "command not found: python" Error

You may encounter this error:

$ python ...
zsh: command not found: python

You'll see this when trying to run Python commands in the terminal. This mostly happens because Python is yet to be installed. However, it is also possible, and more frustrating, that the Python installation is not in the Mac PATH.

If you only need to install and run a Python application, you can use Homebrew to install Pipx. This will install Python as a dependency. Pipx is a tool that allows you to install and run Python applications as standalone executables, avoiding dependency conflicts that can occur when using the standard Python package manager Pip.

If you're going to work on a programming project in Python, install Python with Pyenv, the standard Python version manager. Better yet, install Python with Rye, an all-in-one tool for Python installation, virtual environment management, and package installation.

If you're seeing the zsh: command not found: python error, and are certain you have already installed Python, you may need to update the Mac Python PATH. You'll need to find where Python is installed on your system, which takes some sleuthing because there are multiple ways to install Python on macOS.

Here are the most common locations for Python on a Mac:

1. /usr/bin/python3 is the system Python installed with Xcode Command Line Tools. This is an alias; the actual location is /Library/Developer/CommandLineTools/Library/Frameworks/Python3.framework/Versions/3.9/bin.
2. /opt/homebrew/opt/python@3.12/libexec/bin/python is the Homebrew Python.
3. /Library/Frameworks/Python.framework/Versions/3.12/bin/python3 is the Python installed with the official Python website installer.
4. /Users/username/.pyenv/shims/python is the Python installed with Pyenv.
5. /Users/username/.rye/shims/python is the Python installed with Rye.

Enter the full pathname followed by python --version and see if you get a version number. If you do, you'll need to update your PATH by adding the Python installation path to your .zprofile file. For more information, see Mac PATH.

The article Command not found: python goes into more detail if you need more help.

Using an Out-of-date Python Version

The current Python version is 3.12, as of October 2023. New releases of Python come yearly, typically released in October. The next version, Python 3.13, is expected in October 2024. The newest Python version is listed on the Python website.

Check your Mac Python version:

$ python --version
Python 3.12.4

You should see Python 3.12.4 or a later version. You may not notice issues with an older Python version but it's a good idea to start any project with the newest version. The article about updating Python on Mac explains how to update Python on macOS.

Using the System Python

Macs no longer come with Python pre-installed. But you may have installed Xcode Command Line Tools which includes Python 3.9.6, an older Python version that supports Apple development utilities.

Try python3 --version and which -a python3 to check if Python was installed with Xcode Command Line Tools.

$ python3 --version
Python 3.9.6
$ which -a python3
/usr/bin/python3

If you have Python 3.9.6 installed at /usr/bin/python3, you'll likely have the system Python installed by Xcode Command Line Tools. You can confirm this with xcode-select -p which will show if Xcode Command Line Tools is installed.

$  xcode-select -p
/Library/Developer/CommandLineTools

It's possible to alias python3 to python but I would not recommend using the system Python for development. The system Python is intended for Apple utilities, not for you, so you should install Python on macOS separately if you want to run Python programs or develop in Python.

See my freeCodeCamp article How to Install Python on a Mac to install Python for development.

Using the Homebrew Python

If you use Homebrew as a software package manager, you can easily install Python with brew install python. Homebrew-installed Python is suitable for running scripts but it has drawbacks for installing Python applications or Python software development, when packages are installed.

• Homebrew's automatic updates. Homebrew automatically updates its Python as a dependency for other packages, potentially breaking your projects.
• Multiple projects may need different Python versions. Homebrew-installed Python is a single version and you may need to switch among different versions for different projects.
• Problems with environment isolation. Homebrew provides a single Python environment, which can cause conflicts between projects. Pip, the Python package manager, will block installation of packages unless you first create a virtual environment.

You can check if Python is installed with Homebrew:

$ brew list | grep python
python@3.12

For running applications, it's best to install Pipx and use pipx install instead of pip install to install programs. For Python development, it's best to install Pyenv or install Rye for Python version management and virtual environments.

Missing Pip

READMEs and tutorials often assume users are familiar with Python development tools and instruct them to install Python packages using Pip, the Python package manager. If you've followed instructions that start with pip install <package>, you may have run into the zsh: command not found: pip error.

This is the error you'll see:

$ pip install <package>
zsh: command not found: pip

Pip is installed automatically with Python, so it's unusual to run the python command successfully and then pip and see the error. If you have Python installed, you should be able to use the pip command. You can try a special command that installs Pip:

$ python -m ensurepip --upgrade

If Pip is not already installed, this command will install it. Otherwise, nothing will happen. With this error, it's more likely that you have a Python installation that is not in your Mac Python PATH. See the article Command not found: pip for more details.

Pip Package Installation Errors

You will need to use Pip to install Python packages, unless you are using Rye as an all-in-one tool. However, Pip has some drawbacks.

By default, the pip install <package> command installs the package "globally." This means that the package is added to the global Python site-packages directory, which may result in conflicts if different projects require different versions of the same package.

For example, if project A requires package==1.0 and project B requires package==2.0, installing both packages globally may result in conflicts and dependency hell. Without proper isolation, installing one project's dependencies can cause problems for another. To avoid these conflicts, create a Python virtual environment for each project.

There are two Python tools for creating virtual environments and using different versions of packages. Venv is a built-in Python package. Virtualenv is a more powerful tool with additional features. These tools allow pip to install Python packages into a virtual environment that has its own installation directories and does not share libraries with other virtual environments. Pip must be used in conjunction with either Venv or Virtualenv to successfully install packages.

When you try to install a package with Pip, you may see:

$ pip install <package>
error: externally-managed-environment

Recent versions of pip implement PEP 668 to prevent attempts to install packages globally, which results in the message error: externally-managed-environment. This error occurs when attempting to install a package globally without using a virtual environment. To resolve this error, create a virtual environment using Venv or Virtualenv and install the package within it.

More on Mac Python

You'll need to do more than install Python to begin a programming project, so I've also written a longer article about Mac Python that explains the fundamentals of version management, virtual environments, and package management, as well as comparing various installation options.

Conclusion

A variety of competing development tools means that it can be difficult to get started with Python compared to other programming languages such as JavaScript, Rust, or Ruby. Python is moving towards standardization of tools, and there's rapid innovation as the community seeks to improve the developer experience.

For now, developing Python skills requires some knowledge of the Python ecosystem, the various tools, and how to use them. Still, Python is popular and powerful, and the tutorials on freeCodeCamp will help you learn the language and become a better developer.

Until recently, the language's lack of standard development tooling, plus competing optional-but-essential development tools, meant a rocky start for Python beginners.

To cut through the confusion, I'll show you an up-to-date approach to install Python and set up a programming project, using a single tool named Rye, to install Python versions and software libraries.

Rye is an all-in-one project management tool for Python, written in Rust (for speed) and inspired by Cargo, Rust's comprehensive package manager, from Armin Ronacher, the creator of the Python web framework Flask. It's ideal for beginners, borrowing a folder-based approach to development from other languages such as JavaScript and Ruby.

Contents

You'll want to save the URL for this guide for future reference. Here's what is covered here:

• Before You Get Started
• Python Installation with Rye
• Check for Python
• Install Rye
• Set the PATH for Rye
• Verify Rye installation
• Verify Python installation
• Version and Package Management with Rye
• Create a project with Rye
• Set a version
• Add packages
• Sync to set up the project
• Run Python
• Python Workflow with Rye
• Conclusion

Before You Get Started

You'll need a terminal application, either Mac Terminal or an alternative such as Warp Terminal (a tool I call, "the fastest way to become a command-line power user").

Before you get started, check if you need to update macOS.

You may have heard that Python is pre-installed on your Mac. Older Macs (prior to macOS 12.3) came with Python 2.7. That's an older version, not the Python 3 that you need. Newer Macs don't come with a pre-installed Python.

You'll need to install Xcode Command Line Tools before you begin programming on a Mac. You should check if Xcode Command Line Tools are installed before you proceed further. When you install Xcode Command Line Tools, Apple includes Python 3.9.6. You might be tempted to use it but that's an older version, intended only for system software, which is why you should install a new version of Python, as shown here.

Python Installation with Rye

There are several ways to set up Mac Python. Here are your options, in a nutshell, with a critique.

On the Python.org website, there's an installer application for the most recent Python version. Most Python developers avoid using it because it clutters a Mac in ways that are difficult to manage.

If you install Homebrew for software development, it's easy to "brew install python." However, the Homebrew-installed Python is not well-suited to managing multiple Python projects and development can be cumbersome.

Some tutorials suggest to install Pyenv, a Python version manager. Pyenv is a good choice for managing multiple Python versions, but it requires familiarity with Pip, a package manager, and Venv or Virtualenv, environment managers. Multiple tools make development more complex.

I recommend installing Python with Rye. With this all-in-one tool, you'll manage multiple Python versions, set up project-based environments, and install Python packages without dependency conflicts. I'll show you how to install Python using Rye, the easy way, with a self-install script.

Check for Python

It's best to start with no previous Python version installed, except for the Python version installed by Xcode Command Line Tools.

Try python3 --version and which -a python3 to check if Python was installed with Xcode Command Line Tools:

$ python3 --version
Python 3.9.6
$ which -a python3
/usr/bin/python3

You won't use the Python installed by Xcode Command Line Tools, but it's important to know that Xcode Command Line Tools is already there. Otherwise, install Xcode Command Line Tools.

Check if another version of Python is already installed:

$ python --version
zsh: command not found: python

You'll see zsh: command not found: python if Python is not available. I've written elsewhere about how to update Python if you think you already have Python, as well as a guide to resolving the error "command not found: python" if you are sure Python is installed but not available.

If you have more than one version of Python installed, it's not a problem because you'll set the Mac PATH after installing Rye to make the correct Python version available.

Install Rye

Homebrew is not needed. Rye has a self-install script so you can install Rye with a curl command.

$ curl -sSf https://rye.astral.sh/get | bash

Curl is a command-line tool that makes HTTP requests from the terminal, useful for tasks like downloading and running installation scripts.

$ curl -sSf https://rye.astral.sh/get | bash
This script will automatically download and install rye (latest) for you.
####################################################################### 100.0%
Welcome to Rye!

This installer will install rye to /Users/username/.rye
This path can be changed by exporting the RYE_HOME environment variable.

Details:
  Rye Version: 0.26.0
  Platform: macos (aarch64)

? Continue? (y/n)

Enter y to continue. Rye will ask questions to customize the installation.

? Select the preferred package installer ›
❯ uv (fast, recommended)
  pip-tools (slow, higher compatibility)

By default, Rye offers uv, a faster and newer package installer. I recommend choosing pip-tools for compatibility. If you're a beginner, it will be easier to follow tutorials that refer to pip. Select pip-tools with the arrow keys.

Next, the self-installer asks which Python version you'll use as a default, offering the Rye-installed version or previously-installed versions.

? What should running `python` or `python3` do when you are not inside a Rye managed project? ›
❯ Run a Python installed and managed by Rye
  Run the old default Python (provided by your OS, pyenv, etc.)

It's best to use the Rye-installed version. Accept the default Run a Python installed and managed by Rye by pressing "Enter". Then the self-installer asks which Python version to install as a default.

? Which version of Python should be used as default toolchain? (cpython@3.12) ›

Accept the default and Rye will install the latest Python version. Installation begins when you press "Enter."

Installed binary to /Users/username/.rye/shims/rye
Bootstrapping rye internals
Downloading cpython@3.12.1
Checking checksum
Unpacking
Downloaded cpython@3.12.1
Updated self-python installation at /Users/username/.rye/self

The rye directory /Users/username/.rye/shims was not detected on PATH.
It is highly recommended that you add it.
? Should the installer add Rye to PATH via .profile? (y/n) ›

Notice that Rye installs its Python files to ~/.rye/shims/rye.

Rye offers to set the $PATH to give precedence to its Python version by modifying the .profile file.

Use of the .profile file is a Linux convention. On the Mac, it's preferred to set the $PATH in .zprofile or .zshrc files, preferably .zprofile. Enter n to skip this automatic step. Later, you'll set the $PATH manually.

✔ Should the installer add Rye to PATH via .profile? · no
note: did not manipulate the path. To make it work, add this to your .profile manually:

    source "$HOME/.rye/env"

To make it work with zsh, you might need to add this to your .zprofile:

    source "$HOME/.rye/env"

For more information read https://rye.astral.sh/guide/installation/

All done!

Rye explains how to complete the installation manually by editing the .zprofile file. I'll show you how do it.

Set the PATH for Rye

There's one final important step before Rye works correctly. You must set the Mac PATH to make sure Rye finds the correct Python version. Otherwise, entering the command python will trigger zsh: command not found: python and the command python3 will access the older Xcode-installed Python version.

Edit the ~/.zprofile file. The ~/.zprofile file is used for setting the $PATH. Alternatively, you can modify the ~/.zshrc file (see How Do Zsh Configuration Files Work? for an explanation of the differences). You can use TextEdit, the default macOS graphical text editor, opening a file from the terminal:

$ open -e ~/.zprofile

You also can use the command line editors nano or vim to edit the shell configuration files. See Zsh Shell Configuration for more about editing shell configuration files.

Add this command as the last line of your configuration file to configure the Z shell for Rye:

source "$HOME/.rye/env"

When your terminal session starts, Z shell will run the ~/.rye/env script to set shims to intercept and redirect any Python commands. You'll need double quotes because the command contains special characters.

Rye adds the shims to your $PATH so that running the command python or python3 will run a Rye-installed Python version.

Changes to the ~/.zprofile file will not take effect in the Terminal until you've quit and restarted the terminal. Alternatively (this is easier), you can use the source command to reset the shell environment:

$ source ~/.zprofile

The source command reads and executes a shell script file, in this case resetting the shell environment with your new $PATH setting.

After resetting your shell, you can check the $PATH setting.

$ echo $PATH
/Users/username/.rye/shims:/opt/homebrew/bin:/opt/homebrew/sbin:/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/System/Cryptexes/App/usr/bin:/usr/bin:/bin:/usr/sbin:/sbin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/local/bin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/bin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/appleinternal/bin

The ~/.rye/shims directory should be leftmost, taking precedence over other directories.

Verify Rye installation

After installing Rye, use rye --version to verify that it has been installed.

$ rye --version
rye 0.26.0
commit: 0.26.0 (d245f625e 2024-02-23)
platform: macos (aarch64)
self-python: cpython@3.12
symlink support: true
uv enabled: false

Verify Python installation

Check that Python is available:

$ python --version
Python 3.12.1

Yay! You've installed Python. If you see zsh: command not found: python, check that the Mac PATH is set correctly.

The python3 command should give you the Rye-installed version, not the Xcode-installed version.

$ python3 --version
Python 3.12.1

The which command shows the Rye shims directory when you try to see where Python is installed. Keep in mind that you've set the ~/.zprofile file to use Rye shims to intercept the python command and deliver the Rye-installed versions.

$ which python
/Users/username/.rye/shims/python

You've successfully installed Python with Rye.

Version and Package Management with Rye

You can use Rye to:

1. Set up a Python project.
2. Install a specific Python version for a project.
3. Install Python packages for the project.

Other languages adopt a project-based approach to package management (for example, Rust's Cargo, Ruby's Bundler, and JavaScript's npm). Python has been slow to adopt this approach, but Rye is changing that, eliminating the need for separate tools such as Pyenv, Pip, and Venv for managing versions, software libraries, and environments.

With Rye, you'll start by creating a new project and choosing a Python version. You can then install packages for that project. Rye will manage the Python version and packages for you.

Create a project with Rye

Make a folder for a Python project. Then change directories to the project root:

$ mkdir myproject
$ cd myproject

Specify a Python version for your project:

$ rye pin 3
pinned 3.12.1 in /Users/username/workspace/myproject/.python-version

The command rye pin 3 will create a .python-version file specifying the newest Python version for your project.

You must run the command rye init to create a pyproject.toml file in your project root directory. This is a project-specific configuration file that Rye uses to manage Python versions and packages.

$ rye init
success: Initialized project in /Users/username/workspace/myproject/.
Run `rye sync` to get started

Now you can fetch a Python version and install packages.

Set a version

Rye can install and switch among different Python versions.

Rye uses the term "toolchains" to refer to installed Python versions. To install a Python version, you can fetch a toolchain using Rye.

$ rye fetch
$

If you've specified the default Python with rye pin, rye fetch does nothing. If you specified a different Python version, rye fetch will install the specified version.

$ rye fetch
Downloading cpython@3.12.1
Checking checksum
success: Downloaded cpython@3.12.1

By default, Rye installs all Python executables in a hidden folder in your user home directory ~/.rye/py/. The Rye shims in the Mac $PATH will select the correct Python version you've specified in your project directory,

Add packages

Package managers allow you to download, install, and update software libraries and their dependencies. Most packages depend on other external software libraries—the package manager will fetch and install any dependencies required by that package.

Experienced Python developers are familiar with Pip, the standard package manager for Python, included with any version of Python since Python 3.3.

The command pip install installs packages "globally" into a system Python or shared Python versions, creating potential conflicts.

To safely install Python packages for a specific project with pip, you have to use a Python environment manager such as Venv to create and activate a virtual environment to avoid dependency conflicts.

When you use Rye as an all-in-one tool, you won't need venv for environment management, installing packages directly with Rye.

Before you try to install a package with Rye, be sure you've created a pyproject.toml file in your project root directory with rye init.

You can install any Python package from the Python Package Index. Here we'll install the cowsay utility.

$ rye add cowsay
Added cowsay>=6.1 as regular dependency

If you see error: did not find pyproject.toml, you need to run rye init.

Sync to set up the project

Before you can use a package in a Rye project, you must run rye sync to update lockfiles and install the dependencies into the virtual environment.

$ rye sync
Initializing new virtualenv in /Users/username/workspace/python/myproject/.venv
Python version: cpython@3.12.3
Generating production lockfile: /Users/username/workspace/python/myproject/requirements.lock
Creating virtualenv for pip-tools
Generating dev lockfile: /Users/username/workspace/python/myproject/requirements-dev.lock
Installing dependencies
Looking in indexes: https://pypi.org/simple/
Obtaining file:///. (from -r /var/folders/ls/g23m524x5jbg401p12rctz7m0000gn/T/tmp06o05xiq (line 2))
  Installing build dependencies ... done
  Checking if build backend supports build_editable ... done
  Getting requirements to build editable ... done
  Installing backend dependencies ... done
  Preparing editable metadata (pyproject.toml) ... done
Collecting cowsay==6.1 (from -r /var/folders/ls/g23m524x5jbg401p12rctz7m0000gn/T/tmp06o05xiq (line 1))
  Using cached cowsay-6.1-py3-none-any.whl.metadata (5.6 kB)
Using cached cowsay-6.1-py3-none-any.whl (25 kB)
Building wheels for collected packages: myproject
  Building editable for myproject (pyproject.toml) ... done
  Created wheel for myproject: filename=myproject-0.1.0-py3-none-any.whl size=1074 sha256=0b34a41cbb517a78e5b60593c75e93a37df0bf7958e8921be5f6f6e24a26b5d1
  Stored in directory: /private/var/folders/ls/g23m524x5jbg401p12rctz7m0000gn/T/pip-ephem-wheel-cache-m03jgkok/wheels/8b/19/c8/73a63a20645e0f1ed9aae9dd5d459f0f7ad2332bb27cba6c0f
Successfully built myproject
Installing collected packages: myproject, cowsay
Successfully installed cowsay-6.1 myproject-0.1.0
Done!

Rye displays all its operations but you don't have to read all the details.

Run Python

After installing a package and running rye sync, you can use the Python interpreter interactively (the REPL or Read-Eval-Print Loop).

$ python
Python 3.12.1 (main, Jan  7 2024, 23:31:12) [Clang 16.0.3 ] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import cowsay
>>> cowsay.cow('Hello World')
___________
| Hello World |
  ===========
           \
            \
              ^__^
              (oo)\_______
              (__)\       )\/\
                  ||----w |
                  ||     ||
>>>

Enter quit() or type Control + D to exit the Python interpreter.

Now you're ready to develop any Python project with Rye! You can read the Rye User Guide to learn more.

Python Workflow with Rye

As you code in Python, you'll want to add software libraries to your project. Let's look at an example.

Requests is an HTTP library that you'll likely use in many projects. If you visit the Requests page on PyPI, you'll see the installation instructions:

$ python -m pip install requests

The python -m pip command is a bit cumbersome, and if you use Pip, you have to precede it with python -m venv .venv (to set up a virtual environment) and source .venv/bin/activate (to activate a virtual environment).

With Rye, you can add Requests to your pyproject.toml file.

$ rye add requests

Then run rye sync to install the package.

$ rye sync

Now you can use the Requests library in your Python project, including it with an import statement.

Remember, when you see pip install in a tutorial, you can use rye add and rye sync instead, without additional commands for a virtual environment.

Beginners using pip install often encounter headaches with command not found: pip and error: externally-managed-environment. Rye eliminates these problems.

Conclusion

This article is based on a guide that offers additional details about how to install Python on Mac.

Rye is the new favorite for installing and managing Python because it offers a single coherent setup and packaging system, eliminating the need for separate tools such as Pyenv, Pip, and Venv for managing versions, software libraries, and environments.

Python is the first programming language for most beginners. As it grows in popularity for machine learning and data science, you'll want Python on your Mac for many of the tutorials you'll find on freeCodeCamp.

Zsh shell offers four configuration files with no discernible differences. Particularly, ~/.zshrc and ~/.zprofile appear to be identical, leaving us wondering which one to use.

In this article, you'll learn the difference and a simple guideline for your shell configuration.

Why Do you Need Configuration?

For programming on a Mac, the Terminal application is an essential tool in your development environment. The Terminal is a command-line interface (CLI) that allows you to interact with the operating system and run commands.

The Terminal or console gives you access to the Unix command line, or shell.

Zsh, also known as Z shell, is a program that runs in the Terminal, interprets Unix commands, and interacts with the operating system. Zsh is the default shell program on MacOS.

Before you get started with programming on the Mac, you'll need to configure the shell. There are optional and convenient settings, such as aliases for hard-to-remember commands and a custom prompt that can display the directory you're in, among other things.

There are also some critical environment variables that make programs available or alter shell behavior. The EDITOR environment variable, for example, can set your preferred text editor. Oftentimes, when installing a programming language or software utilities, you need to set the PATH environment variable..

Where to Start

Zsh configuration files are kept in the user's home directory and are named with a dot as the first character to keep them hidden by default.

Zsh recognizes four different configuration files in the user's home directory: ~/.zshenv, ~/.zprofile, ~/.zshrc, and ~/.zlogin.

This is where Zsh configuration becomes puzzling, even for experienced developers. Tutorials rarely explain the differences, especially between the zprofile and zshrc files, leaving curious developers scratching their heads and blindly following instructions.

How is the Shell Used?

To understand the differences among Zsh configuration files, consider various shell uses, which can be classified as interactive or non-interactive, login or non-login sessions.

1. On macOS, each new terminal session is treated as a login shell, so opening any terminal window starts an interactive login session. Also, a system administrator who connects to a remote server via SSH initiates an interactive login session.
2. If a terminal window is already open and you run the command zsh to start a subshell, it will be interactive and non-login. Beginners rarely use subshells.
3. Automated shell scripts run without login or any user prompting. These are non-interactive and non-login.
4. Few people ever encounter a non-interactive login shell session. It requires starting a script with a special flag or piping output of a command into an SSH connection.

How do the Configuration Files Work?

These use cases necessitate different shell configurations, which explains why Zsh supports four different configuration files. Here's how the configuration files are used:

• ~/.zshenv: This is loaded universally for all types of shell sessions (interactive or non-interactive, login or non-login). It is the only configuration file that gets loaded for non-interactive and non-login scripts like cron jobs. However, macOS overrides this for PATH settings for interactive shells.
• ~/.zprofile: Loaded for login shells (both interactive and the rare non-interactive sessions). MacOS uses this to set up the shell for any new terminal window. Subshells that start within the terminal window inherit settings but don't load ~/.zprofile again.
• ~/.zshrc: Loaded only for interactive shell sessions. It is loaded whenever you open a new terminal window or launch a subshell from a terminal window.
• ~/.zlogin: Only used for login shell configurations, loaded after .zprofile. This is loaded whenever you open a new terminal window.

How to Use Each File

With that in mind, let's consider which configuration files you should use.

• ~/.zshenv: It is universally loaded, so you could use it to configure the shell for automated processes like cron jobs. However, it is best to explicitly set up environmental variables for automated processes in scripts and leave nothing to chance. As a beginner, you will not use this configuration file. In fact, few experienced macOS developers use it.
• ~/.zprofile: Homebrew recommends setting the PATH variable here. There's a reason PATH should be set in ~/.zprofile and not the universal ~/.zshenvfile: the macOS runs a utility path_helper (from /etc/zprofile) that sets the PATH order before ~/.zprofile is loaded.
• ~/.zshrc: This is the configuration file that most developers use. Use it to set aliases and a custom prompt for the terminal window. You can also use it to set the PATH (which many people do) but ~/.zprofile is preferred.
• ~/.zlogin: This is rarely used. Only important in managing the order of initialization tasks for login shells in complex environments. It can be used to display messages or system data.

How to Avoid Complications

These configurations may appear complicated. It made sense in the early days of computing to start time-consuming processes at login and not have them repeat when a new terminal was launched.

MacOS now launches any new terminal window as a login shell, loading both ~/.zprofile and ~/.zshrc files without concern for the shell startup time. So why not use one Zsh configuration file? A bow to history, plus configuration customization for the experts.

The key advantage of the ~/.zprofile file (versus ~/.zshenv) is that it sets environment variables such as PATH without override from macOS. The ~/.zshrc file could be used for the same but, by convention and design, is intended for customizing the look and feel of the interactive terminal.

Keep It Simple

If you're looking for simple guidelines, here's the current best practice.

• Use ~/.zprofile to set the PATH and EDITOR environment variables.
• Use ~/.zshrc for aliases and a custom prompt, tweaking the appearance and behavior of the terminal.
• If you write automated shell scripts, check and set environment variables in the script.

More Information

I've written other guides that go into detail about the following:

• Mac Terminal
• Shell Configuration
• Mac PATH.

If you're just getting started, you'll need to know How to Open Mac Terminal and Install Xcode Command Line Tools.

Configuring the Zsh shell is a critical step in preparing your Mac development environment. With your development environment set up, you'll be prepared for any tutorial you'll find on freeCodeCamp.

Apple provides a complete development environment for programmers named Xcode. If you are developing software for macOS, iOS, tvOS, and watchOS, you must install the full Xcode application.

It's not pre-installed, but you can install it from the Apple developer website or the App Store on your Mac.

What are Xcode Command Line Tools?

If you're not developing software for an Apple device, you won't need the full Xcode application (it requires over 40GB of disk space!).

Instead, you'll install Xcode Command Line Tools. It's a smaller package for software developers with tools that run on the command line, that is, in the Terminal application.

Programmers have used these tools on Unix operating systems since computing's beginnings, and they serve as the foundation of almost all software development.

Luckily, the Xcode Command Line Tools package only requires 1.2GB of space on your disk.

You have three choices to install Xcode Command Line Tools on a Mac:

• install the full Xcode package
• install Xcode Command Line Tools when triggered by a command
• install Xcode Command Line Tools as part of a Homebrew installation.

I don't recommend installing the full Xcode package unless you're developing software for an Apple device. The download will take too long and it will consume unnecessary disk space. Instead, try either of two faster methods.

How to Install Xcode Command Line Tools from a Command Prompt

Apple has made it easy to install Xcode Command Line Tools because certain commands will prompt you to begin installation.

Here are examples of commands that will trigger a prompt to install Xcode Command Line Tools:

• clang – a compiler that turns source code into an executable program
• gcc – the GNU compiler
• git – the save-as-you-go version control system

Running any of these commands in the terminal will bring up a prompt to install Xcode Command Line Tools. I've written elsewhere about How to Open Terminal on MacOS – just click the Spotlight icon in the menu bar and type “terminal.”

You can also enter the command xcode-select --install in the terminal to begin the installation process. You'll see a panel that asks you to install Xcode Command Line Tools.

Click 'Install' to begin the download and installation process.

Installation takes 8 minutes on a 2021 Mac M1 Mini, with a 100Mbps Internet connection. It's significantly slower on Mac Intel over a slow Internet connection.

You'll see a confirmation message when installation is complete.

Verify that you've successfully installed Xcode Command Line Tools:

$ xcode-select -p

You should see the following:

/Library/Developer/CommandLineTools

How to Use Homebrew to Install Xcode Command Line Tools

As easy as it is to use the command prompt to install Xcode Command Line Tools, I recommend an even easier method: using Homebrew.

This option was only recently added to Homebrew, so many developers are not aware of it.

Homebrew is the popular Mac package manager. Most developers need programming languages and utilities that don't come installed on macOS and are not included in the Xcode Command Line Tools package. Homebrew can install almost any open-source tool for developers.

Since you'll probably need Homebrew, you might as well let Homebrew install Xcode Command Line Tools for you.

First, check if Homebrew is already installed.

$ brew

If Homebrew is not installed, you will see:

zsh: command not found: brew

Homebrew provides an installation script you can run with a single command (check that it hasn't changed at the Homebrew site).

$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

The Homebrew installation script will ask you to enter your Mac user password. This is the password you use to sign in to your Mac.

Password:

You won't see the characters as you type. Press enter when you are done.

If you haven't already installed Xcode Command Line Tools, you'll see a message that "The Xcode Command Line Tools will be installed." Press return to continue when prompted by the Homebrew installation script.

You’ll see diagnostic and progress messages. Homebrew installation takes 2 to 15 minutes on a 2021 Mac M1 Mini, with a 100Mbps Internet connection. It's significantly slower on Mac Intel over a slow Internet connection.

On Mac Intel machines, that's all you need to do – Homebrew is ready to use. On Mac Intel, Homebrew installs itself into the /usr/local/bin directory, which is already configured for access by the shell with the macOS default $PATH.

On Apple Silicon machines, there's one more step. Homebrew files are installed into the /opt/homebrew folder. But the folder is not part of the default $PATH. Follow Homebrew's advice and create a ~/.zprofile file that contains a command which sets up Homebrew. Homebrew shows instructions at the end of the installation process:

- Add Homebrew to your PATH in ~/.zprofile:
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

After you've installed Homebrew, check that Homebrew is installed properly.

$ brew doctor

You should see this:

Your system is ready to brew.

If Homebrew is successfully installed, there will be Homebrew files in /usr/local (for macOS Intel) or /opt/homebrew (for Apple Silicon).

Now you have both Xcode Command Line Tools and Homebrew installed. If you want to learn more about adding Homebrew packages to set up your development environment, see Install a Homebrew Package.

More information

I've written an in-depth guide to Install Xcode Command Line Tools that goes beyond these basics.

In the guide, I explain how to check if Xcode Command Line Tools Are Already Installed. I go into more detail about how to Install Xcode Command Line Tools with Homebrew. Finally, I explain how to Uninstall Xcode Command Line Tools, Reinstall Xcode Command Line Tools, and provide a List of Xcode Command Line Tools that you can use.

There's also a complete guide to Install Homebrew for Mac that explains how to Update Homebrew, Uninstall Homebrew, and keep up with other Housekeeping for Homebrew.

Your development environment

MacOS is the most popular platform for software development because the operating system is based on Unix, the longtime standard for software development.

With Xcode Command Line Tools installed, you'll have a solid foundation for adding almost any open source development tool.

Add Homebrew and you have a package manager that can install version managers, programming languages, and almost any other tool you may need.

Combined with a text editor and terminal application, you'll be prepared for any tutorial you'll find on freeCodeCamp.

Which Ruby do you have?

MacOS comes with a "system Ruby" pre-installed.

Use the which command to see where Ruby is installed:

$ which ruby
/usr/bin/ruby

If you see /usr/bin/ruby, it is the pre-installed macOS system Ruby.

It's fine to use the system Ruby for running sysadmin scripts, as long as you don't alter the system Ruby by attempting to update it or add gems.

But you don't want to use it when you are developing projects in Ruby.

Ruby for development

For developing projects with Ruby, you should Install Ruby with Homebrew or use a version manager such as asdf, chruby, rbenv, or rvm.

A version manager helps if you're juggling multiple projects and can't update all at once. For a guide that compares version managers and shows the best way to install Ruby, see my article Install Ruby on a Mac.

But why not use the macOS default Ruby? Let's take a look at the reasons why it's a bad idea to use the Mac default Ruby for development.

Gem installation hassles

RubyGems are the ready-made software libraries that make development easy and fun in Ruby. Most Ruby projects use at least a few gems.

If you use the Mac system Ruby, running gem install will try to save gems to the system Ruby directory /Library/Ruby/Gems/2.6.0. That directory is owned by root, the system superuser. Ordinary users are not allowed to write to it (and you really shouldn't alter this folder).

If you try to install a gem, for example gem install rails, you'll get a permissions error:

ERROR: While executing gem ... (Gem::FilePermissionError)
You don't have write permissions for the /Library/Ruby/Gems/2.6.0 directory

It violates system security

Unix-based systems are powerful, so there's a workaround. You can install gems as a superuser to override the permissions restriction. But don't do this!

$ sudo gem install rails

Any time you are about to run sudo, you should stop and ask if you're about to shoot yourself in the foot.

In this case, you need sudo because you're altering system files that are managed by the OS. Don't do it! You may leave the system in a broken or compromised state. Even worse, a gem might contain malicious code that tampers with your computer.

Gem management

Experienced developers use Bundler to install gems and manage their dependencies.

Imagine you've got projects that use different versions of a gem (maybe there was a new gem release between your projects). Or maybe two different gems in your project rely on different versions of a dependent gem.

Bundler uses a Gemfile in your project directory to keep track of the gems you need. If you were to use sudo to install gems with the system Ruby, you'd end up with a mess of incompatible gems in the system Ruby directory.

You can work around the systems permission problem by installing Bundler with a command that uses your home directory for gems. But it's easier to install Ruby with Homebrew or use a version manager and use the Bundler that comes installed, which will correctly set up your local development environment.

Use the newest Ruby

When you start a project, use the newest Ruby release (it's 3.0 at the time this was written).

The system Ruby in macOS Catalina or Big Sur is Ruby 2.6.3, which is old. If you're just starting with Ruby, install with Homebrew and work on a project with Ruby 3.0. When you start building another project, it may be time to install a version manager so you can juggle projects with different Ruby versions.

MacOS after Big Sur

MacOS Big Sur is now the current version. Apple says:

"Scripting language runtimes such as Python, Ruby, and Perl are included in macOS for compatibility with legacy software. Future versions of macOS won’t include scripting language runtimes by default, and might require you to install additional packages."

If you're reading this at the end of 2021, the system Ruby may already be gone. If not, prepare yourself by installing Ruby with Homebrew or a version manager.

Enjoy Ruby

For developers planning to build web applications with Rails, I've written a guide, Install Rails on a Mac, which goes beyond Install Ruby on a Mac to show how to pick a version manager that will work with Node as well as Ruby.

Enjoy the pleasure of coding in Ruby! After all, it is known as a language dedicated to programmer happiness. But remember, the system Ruby is there for macOS, not for you.