Setting up Rye on Windows

TL;DR: Do not run pipx install rye. Instead, first enable Developer Mode in Windows, and then use the official Rye installer.

Rye is a tool for managing python projects and their dependencies, in a similar vein as Poetry and Pipenv. These notes cover how (not) to set up Rye on Windows.

Installing Rye via pipx §

First, I naïvely tried to install Rye with pipx. It does not work:

PS C:\Users\sam> pipx install rye 

Fatal error from pip prevented installation. Full pip output in file: 
    C:\Users\sam\AppData\Local\pipx\pipx\10gs\cmd_2024—07—23_09.25.09_pip_errors.log

pip seemed to fail to build package: 
    pyyam1<6.O.O,>=5.1.2 

Some possibly relevant errors from pip install: 
    error: subprocess—exited—with—error 
    AttributeError: cython_sources 

Error installing rye. 

Installing Rye via the official installer (first attempt) §

Next, I went to the official instructions.

Welcome to Rye! 

Rye has detected that it's not installed on this computer yet and 
automatically started the installer for you. For more information 
read https://rye.astral.sh/guide/installation/

This installer will install rye to C:\Users\sam\.rye 
This path can be changed by exporting the RYE_HOME environment variable. 

Details:
  Rye Version: 0.37.0
  Platform: windows (x86_64) 

warning: your Windows configuration does not support symlinks.

It's strongly recommended that you enable developer mode in Windows to
enable symlinks. You need to enable this before continuing the setup.
Learn more at https://rye.astral.sh/guide/faq/#windows-developer-mode

? Continue? (y/n) >

It strongly recommends enabling developer mode:

If you do not, then:

• Virtualenvs will be created as copies rather than symlinks.
• Executables in .rye/py will be non-executable as they will be proxy files.
• Shims will be installed as hardlinks, which can cause issues updating Rye when Python is in use.
• More disk space may be used, as virtualenvs may not be deleted correctly.

In some places, junction points will used instead of symlinks, which may not be handled properly by other applications.

So I decided to abort the install and enable developer mode first.

Enabling developer mode in Windows §

To enable developer mode in Windows:

• Open start menu and search for developer settings.
• Open the developer settings window, and enable Developer Mode.

Installing Rye via the official installer (second attempt) §

With developer mode enabled, I ran the installer again:

Welcome to Rye!

Rye has detected that it's not installed on this computer yet and
automatically started the installer for you. For more information
read https://rye.astral.sh/guide/installation/ 

This installer will install rye to C:\Users\sam\.rye 
This path can be changed by exporting the RYE_HOME environment variable. 

Details: 
  Rye Version: 0.37.0
  Platform: windows (x86_64) 

✔ Continue? · yes
✔ Select the preferred package installer · uv (fast, recommended)
✔ What should running `python` or `python3` do when you are not inside a Rye managed project? · Run the old default Python (provided by your OS, pyenv, etc.)
Installed binary to C:\Users\sam\.rye\shims\rye.exe
Bootstrapping rye internals
Downloading cpython@3.12.4 
Checking checksum 
Unpacking 

The non-ASCII characters did not display in my Windows Command Prompt (they showed as � character), so I dug into the Rye source to figure out what characters they should have been.¹

Note that:

• You can use RYE_HOME to override the default install location.
• The installer provides a few prompts:
  • You can choose the package installer. I went with uv as the default.
  • You can choose what python and python3 do outside of a Rye managed project. I chose to use the default Python, so that Rye does not break any existing Python projects I have.

Path §

On Windows, there is no need to add Rye to the PATH. The installer will do that automatically.

Rye added %USERPROFILE%\.rye\shims to the environment variables for my account, not for the whole system. This means Rye will only be available for my account. Not an issue, just something to be aware of.

Verify Rye is installed §

Run rye --version just to check rye is on the PATH and see what version we have:

$ rye --version
rye 0.37.0
commit: 0.37.0 (09b67c469 2024-07-20)
platform: windows (x86_64)
self-python: cpython@3.12.4
symlink support: true
uv enabled: true

All done! Rye is ready for use.