Python is the most popular first language for programmers on a Mac.

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

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-up.com/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-up.com/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-up.com/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.