Install Rye Python Toolchain Guide

Rye is a modern Python toolchain that simplifies managing Python versions, virtual environments, and project dependencies. It is fast, reliable, and works on Linux, macOS, and Windows.

This guide walks you through installing Rye from scratch. You will learn how to set it up, verify the installation, and create your first project. By the end, you will have a clean and efficient Python workflow.

What is Rye?

Rye is a toolchain built by Armin Ronacher, the creator of Flask. It combines the best features of tools like pyenv, poetry, and pipenv into one unified system. Rye handles Python version downloads, virtual environment creation, and dependency management automatically.

Unlike other tools, Rye uses a single configuration file called pyproject.toml for all project settings. This reduces complexity and keeps your project organized.

System Requirements

Before installing Rye, ensure your system meets these requirements:

• Linux (Ubuntu, Debian, Fedora, Arch), macOS (10.15+), or Windows (10/11 with PowerShell)
• Internet connection to download Rye and Python versions
• Basic command line knowledge

Rye requires no prior Python installation. It downloads and manages Python versions for you.

Step 1: Install Rye

The easiest way to install Rye is using the official installer script. Open your terminal and run:

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

This command downloads and executes the installer. It places Rye in ~/.rye by default. The installer also adds Rye to your PATH.

After installation, restart your terminal or run:

source ~/.rye/env

For Windows users, use PowerShell as administrator:

powershell -c "irm https://rye.astral.sh/get | iex"

Step 2: Verify Installation

Check that Rye installed correctly by asking for its version:

rye --version

You should see output similar to:

rye 0.35.0

If the command is not found, ensure ~/.rye/shims is in your PATH. You can add it manually:

export PATH="$HOME/.rye/shims:$PATH"

Add this line to your shell configuration file (.bashrc, .zshrc, or .profile) to make it permanent.

Step 3: Install a Python Version

Rye manages Python versions for you. To install a specific version, use rye toolchain fetch. For example, to install Python 3.12:

rye toolchain fetch 3.12

Rye downloads the official Python build from python.org and stores it in ~/.rye/py. The process takes a minute or two.

List all available toolchains:

rye toolchain list

Output example:

[email protected] (downloaded)
[email protected] (downloaded)

You can install multiple Python versions and switch between them per project.

Step 4: Create a New Project

Now create a Python project with Rye. Navigate to your workspace and run:

rye init my_project
cd my_project

This generates a basic project structure with a pyproject.toml file. The file contains metadata and dependencies.

Set the Python version for this project:

rye pin 3.12

This command updates .python-version to use Python 3.12. Rye automatically creates a virtual environment when you run rye sync.

Step 5: Add Dependencies

Add a dependency like requests:

rye add requests

Rye updates pyproject.toml and installs the package into the virtual environment. The rye sync command runs automatically after adding.

Check the pyproject.toml file:

# pyproject.toml
[project]
name = "my_project"
version = "0.1.0"
dependencies = [
    "requests>=2.31.0",
]

You can also add development dependencies with --dev flag:

rye add --dev pytest

Step 6: Run Python Code

Create a simple script in src/my_project/main.py:

# src/my_project/main.py
import requests

response = requests.get("https://api.github.com")
print(f"Status: {response.status_code}")

Run it using Rye:

rye run python src/my_project/main.py

Output:

Status: 200

Rye activates the virtual environment automatically when running commands. You can also use rye shell to enter the environment interactively.

Step 7: Update and Remove Toolchains

To update Rye itself:

rye self update

To remove an unused Python version:

rye toolchain remove 3.11

This cleans up the downloaded toolchain and frees disk space.

Common Commands Reference

Here is a quick reference for daily Rye commands:

• rye init project_name – Create a new project
• rye pin 3.12 – Set Python version
• rye add package – Add a dependency
• rye sync – Synchronize environment
• rye run command – Run a command in the environment
• rye shell – Enter virtual environment shell
• rye toolchain list – List installed Python versions

Benefits of Using Rye

Rye simplifies Python development in several ways:

• Unified management – One tool for Python versions, environments, and dependencies.
• Fast performance – Rye uses caching and parallel downloads.
• Standard compliance – Uses pyproject.toml and PEP standards.
• Cross-platform – Works on Linux, macOS, and Windows.
• No global conflicts – Each project has its own Python and dependencies.

If you are migrating from tools like pyenv or poetry, Rye offers a smoother and more integrated experience.

Conclusion

Installing Rye Python toolchain is a straightforward process that takes only a few minutes. With Rye, you can manage Python versions, virtual environments, and dependencies from a single command-line interface.

Start by running the installer script, verify the installation, fetch a Python version, and create your first project. The steps in this guide work on all major operating systems and require no prior Python setup.

Using Rye improves your productivity and keeps your development environment clean and reproducible. Try it today and simplify your Python workflow.