Python

audience developer
level all
topic Python
subtopic Installation

Install Python with Rye

How to install Python with Rye on Mac. Rye for Python version and package management. Rye, an all-in-one tool for Python development.

For most of its existence, Python has been plagued by a lack of standard development tooling which makes it difficult to set up a trouble-free development environment. Several tools emerged to simplify work in Python development environments, including Poetry, Hatch, PDM, and Rye. Until September 2024, Rye was a leading favorite but UV is now preferred over Rye.

Rye's features are being merged into UV, so the ecosystem is consolidating around UV as a single coherent setup and packaging system for Python. Rye is still usable and maintained, but UV is now preferred, and recommended as a successor project from the same maintainers.

This guide describes how to install Rye, and it is still usable, but I recommend installing and using UV.

Before you get started

You'll need a terminal application to install and use Python. Apple includes the Mac terminal but I prefer Warp Terminal. Warp increases developer productivity, helping you remember easily-forgotten commands and adds AI troubleshooting. Download Warp Terminal now; it's FREE and worth a try.

Why Rye?

Rye was one of the first Python tooling projects to offer a single coherent setup and packaging system, eliminating the need for separate tools such as pip, pyenv, and venv for managing versions, software libraries, and environments. For projects that were more complex than a simple script or utility, developers used Rye to install Python and software libraries.

Install Pyenv or Rye?

Pyenv has been a long-time favorite for managing Python versions (we also have a guide to Install Pyenv). If you want to use Pyenv, it's recommended to install Pyenv with Homebrew and you'll also need to install Venv or Virtualenv and use Pip. Rye doesn't require Homebrew and eliminates the need for these other tools. UV also has this advantage.

Steps

There is no need to install Python before installing Rye. Rye will install Python for you.

Here's how to install one or more Python versions on Mac and manage Python development with Rye:

  1. Check macOS and update macOS.
  2. Check if Xcode Command Line Tools are installed.
  3. Install Rye with a self-install script (it will install the latest Python).
  4. Set the Mac PATH for Python to make sure you use the correct version of Python.

Rye is a single tool for version management and package management. If you choose to use Rye, install the Rye tool from the command line before installing one or more Python versions.

Check for Python

You'll need Xcode Command Line Tools for software development, and with Xcode, Apple includes Python 3.9.6. As of October 2024, the latest Python version is 3.13.

You should not attempt to update or remove the system Python installed with Xcode Command Line Tools. Just install a newer Python version with Rye.

Install Rye

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/daniel/.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? ([email protected]) ›

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

Installed binary to /Users/daniel/.rye/shims/rye
Bootstrapping rye internals
Downloading [email protected]
Checking checksum
Unpacking
Downloaded [email protected]
Updated self-python installation at /Users/daniel/.rye/self

The rye directory /Users/daniel/.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.

You can use TextEdit, the default macOS graphical text editor, to edit the ~/.zprofile file. Alternatively, you can edit the ~/.zshrc file. It works the same but, by convention and design, the ~/.zprofile file is used for setting the $PATH (see .zshrc or .zprofile for an explanation). You can open a file in TextEdit from the terminal:

$ open -e ~/.zprofile

You also can use the command line editors nano or vim to edit the shell configuration files. See 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 spaces or 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 # Or just restart your terminal

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: [email protected]
symlink support: true
uv enabled: false

Verify Python installation

Check that Python is available:

$ python --version
Python 3.12.1

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/daniel/.rye/shims/python

You've successfully installed Python with Rye.

Use Rye

You can use Rye to:

  1. Set up a Python project.
  2. Install more than one Python version.
  3. Install Python packages for each project.

Next, see our guide:

The guide explains how to use Rye instead of Pyenv or Pip.

Uninstall Rye

Here's how to remove Rye, if you decide not to use it.

$ rye self uninstall
✔ Do you want to uninstall rye? · yes
Done!
Don't forget to remove the sourcing of $HOME/.rye/env from your shell config.

Rye will uninstall itself but you will need to delete the ~/.rye/ hidden directory in your user home directory.

$ rm -rf ~/.rye/

Finally, use a text editor to remove this line from your ~/.zprofile file:

source "$HOME/.rye/env"

You've uninstalled Rye.

What's next

My mac.install.guide is a trusted source of installation guides for professional developers. Take a look at the Mac Install Guide home page for tips and trends and see what to install next.