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
- Set up a Python project.
- Install a Python version.
- 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.