Skip to content

Installation

Rye is built in Rust. It can either be manually compiled and installed or it can be installed from a binary distribution. It has support for Linux, macOS and Windows.

Installing Rye

Rye is installed per-user and self manages itself. It will install itself into a folder in your home directory and manage itself there.

To install you can run a curl command which will install the right binary for your operating system and CPU architecture and install it:

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

Alternatively if you don't trust this approach, you can download the latest release binary. On first run it will install itself.

gunzip rye-x86_64-linux.gz
chmod +x ./rye-x86_64-linux
./rye-x86_64-linux

To install you can run a curl command which will install the right binary for your operating system and CPU architecture and install it:

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

Alternatively if you don't trust this approach, you can download the latest release binary. On first run it will install itself.

gunzip rye-aarch64-macos.gz
chmod +x ./rye-aarch64-macos
./rye-aarch64-macos

To install Rye on windows download the latest release and run the binary. Upon first run it will install itself. Please note that it's strongly recommended to have "Developer Mode" activated when using Rye and before starting the installation. Learn more.

Note

Rye does not yet use signed binaries which means that you will need to allow the execution of the downloaded executable. If there is no obvious way to do so, click on "More info" on the error message that shows up and then on "Run anyway".

Additionally sometimes a Trojan warning about "Bearfoos" is shown. This is a false positive. For more information see the discussion Windows Bearfoos virus associated with rye.

You need to have Rust and Cargo installed. If you don't have, you can use rustup to get them onto your machine.

Afterwards you can install Rye via cargo:

cargo install --git https://github.com/astral-sh/rye rye

Rye will automatically download suitable Python toolchains as needed. For more information about this read about toolchains. To install a specific version download a binary directly from GitHub.

Customized Installation

On some platforms there is some limited support for customizing the installation experience. This for instance can be necessary on certain Linux environments such as Alpine where the Rye provided Python interpreter is not supported.

The install script that is piped to bash can be customized with some environment variables:

RYE_VERSION

Defaults to latest. Can be set to an explicit version to install a specific one.

RYE_INSTALL_OPTION

Can optionally be set to "--yes" to skip all prompts.

RYE_TOOLCHAIN

Optionally this environment variable can be set to point to a Python interpreter that should be used as the internal interpreter. If not provided a suitable interpreter is automatically downloaded.

At present only CPython 3.9 to 3.12 are supported.

RYE_TOOLCHAIN_VERSION

For Rye 0.22 and later a specific Python version can be picked rather than the default. This affects the internal toolchain version only. It's useful for Docker builds where you can set the internal toolchain to the same as your project to only fetch a single Python.

At present only CPython 3.9 to 3.12 are supported.

This for instance installs a specific version of Rye without asking questions:

curl -sSf https://rye.astral.sh/get | RYE_VERSION="0.4.0" RYE_INSTALL_OPTION="--yes" bash

The install script that is piped to bash can be customized with some environment variables:

RYE_VERSION

Defaults to latest. Can be set to an explicit version to install a specific one.

RYE_INSTALL_OPTION

Can optionally be set to "--yes" to skip all prompts.

RYE_TOOLCHAIN

Optionally this environment variable can be set to point to a Python interpreter that should be used as the internal interpreter. If not provided a suitable interpreter is automatically downloaded.

At present only CPython 3.9 to 3.12 are supported.

RYE_TOOLCHAIN_VERSION

For Rye 0.22 and later a specific Python version can be picked rather than the default. This affects the internal toolchain version only. It's useful for Docker builds where you can set the internal toolchain to the same as your project to only fetch a single Python.

At present only CPython 3.9 to 3.12 are supported.

This for instance installs a specific version of Rye without asking questions:

curl -sSf https://rye.astral.sh/get | RYE_VERSION="0.4.0" RYE_INSTALL_OPTION="--yes" bash

The Windows installer has limited support for customizations via environment variables. To set these you need to run the installer from cmd.exe.

RYE_TOOLCHAIN

Optionally this environment variable can be set to point to a Python interpreter that should be used as the internal interpreter. If not provided a suitable interpreter is automatically downloaded.

At present only CPython 3.9 to 3.12 are supported.

RYE_TOOLCHAIN_VERSION

For Rye 0.22 and later a specific Python version can be picked rather than the default. This affects the internal toolchain version only. It's useful for Docker builds where you can set the internal toolchain to the same as your project to only fetch a single Python.

At present only CPython 3.9 to 3.12 are supported.

This for instance installs Rye with a specific toolchain:

set RYE_TOOLCHAIN=%USERPROFILE%\AppData\Local\Programs\Python\Python310\python.exe
rye-x86_64-windows.exe

Add Shims to Path

Once rye is installed you need to add the shims folder into your PATH. This folder is a folder that contains "shims" which are executables that Rye manages for you as well as the rye executable itself. For instance any Python installation managed by Rye will be available via a shim placed there.

On macOS or Linux you can accomplish this by adding it to your .profile file or similar. This step is technically optional but required if you want to be able to just type python or rye into the shell to pick up the current virtualenv's Python interpreter. The installer will offer to do this for you automatically. If you opt-out, or you run a custom shell you will need to do this manually.

Rye ships an env file which should be sourced to update PATH automatically.

echo 'source "$HOME/.rye/env"' >> ~/.profile

In some setups .profile is not sourced, in which case you can add it to your .bashrc:

echo 'source "$HOME/.rye/env"' >> ~/.bashrc

Rye ships an env file which should be sourced to update PATH automatically.

echo 'source "$HOME/.rye/env"' >> ~/.zprofile

In some setups .zprofile is not sourced, in which case you can add it to your .zshrc:

echo 'source "$HOME/.rye/env"' >> ~/.zshrc

Since fish does not support env files, you need to add the shims directly. This can be accomplished by running this command once:

set -Ua fish_user_paths "$HOME/.rye/shims"

Since nushell does not support env files, you need to add the shims directly. This can be accomplished by adding this to your env.nu file:

$env.PATH = ($env.PATH | split row (char esep) | append "~/.rye/shims")

Rye ships an env file which should be sourced to update PATH automatically.

echo '. "$HOME/.rye/env"' >> ~/.profile

The windows installer normally will automatically register the rye path in the PATH environment variable. If this does not work you will need to manually perform the following steps:

  1. Press Win+R, enter sysdm.cpl and hit Enter.
  2. In the "System Properties" dialog, click the "Advanced" tab.
  3. Click on "Environment Variables".
  4. In the top list, double click on the Path variable.
  5. In the "Edit environment variable" dialog click on "New".
  6. Enter %USERPROFILE%\.rye\shims and hit Enter.
  7. Click repeatedly on "Move Up" until the newly added item is at the top.
  8. Click on "OK" and close the dialog.

Note that you might need to restart your login session for this to take effect.

There is a quite a bit to shims and their behavior. Make sure to read up on shims to learn more.

Shell Completion

Rye supports generating completion scripts for Bash, Zsh, Fish, Powershell and Nushell. Here are some common locations for each shell:

mkdir -p ~/.local/share/bash-completion/completions
rye self completion > ~/.local/share/bash-completion/completions/rye.bash

# Make sure ~/.zfunc is added to fpath, before compinit.
rye self completion -s zsh > ~/.zfunc/_rye

Oh-My-Zsh:

mkdir $ZSH_CUSTOM/plugins/rye
rye self completion -s zsh > $ZSH_CUSTOM/plugins/rye/_rye

Then make sure rye plugin is enabled in ~/.zshrc

rye self completion -s fish > ~/.config/fish/completions/rye.fish

# Create a directory to store completion scripts
mkdir $PROFILE\..\Completions
echo @'
Get-ChildItem "$PROFILE\..\Completions\" | ForEach-Object {
    . $_.FullName
}
'@ | Out-File -Append -Encoding utf8 $PROFILE
# Generate script
Set-ExecutionPolicy Unrestricted -Scope CurrentUser
rye self completion -s powershell | Out-File -Encoding utf8 $PROFILE\..\Completions\rye_completion.ps1

rye self completion -s nushell | save --append $nu.env-path

Updating Rye

To update rye to the latest version you can use rye itself:

rye self update

Uninstalling

If you don't want to use Rye any more, you can ask it to uninstall it again:

rye self uninstall

Additionally you should delete the remaining .rye folder from your home directory and remove .rye/shims from the PATH again (usually by removing the code that sources the env file from the installation step). Rye itself does not place any data in other locations. Note though that virtual environments created by rye will no longer function after Rye was uninstalled.

Preventing Auto Installation

Rye when launched will normally perform an auto installation. This can be annoying in certain development situations. This can be prevented by exporting the RYE_NO_AUTO_INSTALL environment variable. It needs to be set to 1 to disable the feature.

export RYE_NO_AUTO_INSTALL=1

export RYE_NO_AUTO_INSTALL=1

set RYE_NO_AUTO_INSTALL=1