Python

audience developer
level all
topic Python
subtopic Installation

Use Rye for Python

How to use Rye for Python development on Mac. Rye for Python version management. Rye for Python package management.

Rye combines Python version management and package management in a single tool. Before Rye was available, Pyenv was a popular choice for managing Python versions, in combination with Pip for installing Python packages which also required Venv or Virtualenv, environment managers. Now Rye is a one-stop version and package management solution. This guide shows how to use Rye.

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.

You can install Rye from the command line. Start with this:

After installing Rye you can set up Python projects, install additional Python versions, and install Python packages.

What's Here

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

If you already have Python installed from another source, it's best to install the latest Python version with Rye and set the Mac Python PATH to use Rye.

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 Python PATH is set correctly. See Install Python with Rye for help.

How to manage Python projects with Rye

Typically, you'll install a programming language system-wide or with a version manager before starting a project. Installing Rye installs the latest Python version as a default. However, Rye can also perform Python installation as part of a project set up, which is a better approach for multiple projects.

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/daniel/workspace/myproject/.python-version

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

You should also run the command rye init to create a pyproject.toml file in your project root directory.

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

Now you can fetch a Python version and install packages.

Python versions with Rye

Rye is an alternative to Pyenv that 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, rye fetch does nothing. If you specified a different Python version, rye fetch will install the specified version.

$ rye fetch
Downloading [email protected]
Checking checksum
success: Downloaded [email protected]

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,

Python packages with Rye

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.

Pip is the standard package manager for Python, included with any version of Python since Python 3.3. If you've used Node to run JavaScript, pip is similar to npm, the Node package manager. However, npm install installs packages within a project by default, whereas pip install installs packages into a system Python or shared Python versions, creating potential conflicts. To install Python packages for a specific project with pip, it's best to use a Python environment manager such as Venv to create and activate a virtual environment. You'll avoid dependency conflicts when you have multiple projects that require different versions of the same packages. If you use Rye as an all-in-one tool, you won't need venv or virtualenv for environment management and you can install packages directly with Rye. With Rye, it's much easier to install packages.

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.

Rye sync

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
Reusing already existing virtualenv
Generating production lockfile: /Users/daniel/workspace/myproject/requirements.lock
Creating virtualenv for pip-tools
Generating dev lockfile: /Users/daniel/workspace/myproject/requirements-dev.lock
Installing dependencies
Looking in indexes: https://pypi.org/simple/
Obtaining file:///. (from -r /var/folders/ls/g23m524x5jbg401p12rctz7m0000gn/T/tmpyzjrebff (line 2))
  Installing build dependencies ... done
  Checking if build backend supports build_editable ... done
  Getting requirements to build editable ... done
  Preparing editable metadata (pyproject.toml) ... done
Collecting cowsay==6.1 (from -r /var/folders/ls/g23m524x5jbg401p12rctz7m0000gn/T/tmpyzjrebff (line 1))
  Downloading cowsay-6.1-py3-none-any.whl.metadata (5.6 kB)
Downloading 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=1066 sha256=13905ba3ed5b7de2a39c0eedea6a9be9e7d8a7750aa602a4ea78c27da3f9dfe8
  Stored in directory: /private/var/folders/ls/g23m524x5jbg401p12rctz7m0000gn/T/pip-ephem-wheel-cache-pkuzm62h/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 any of 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.

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.