Rye: An Experimental Python Package Manager and Practical Usage Guide

Rye, an experimental Python package management system authored by Armin Ronacher (the creator of Flask), was introduced to tackle the fragmentation of the current Python packaging ecosystem, which includes tools such as poetry, pip, pipenv, pyenv, virtualenv, pdm, and hatch.

The article explains the drawbacks of existing tools, the challenges of environment management with conda, and the confusion caused by system‑installed versus user‑installed Python versions, referencing PEP 668 and PEP 711 as ongoing efforts to standardize Python distribution.

Inspired by Rust’s unified toolchain (rustup and cargo), Rye proposes a workspace model where each workspace contains a single Python version, isolates versions across workspaces, and uses pyproject.toml for configuration.

Introduce a workspace concept similar to a project directory or Git repository, with one Python version per workspace.

Download a standalone Python interpreter per project, avoiding system Python and pip exposure; manage dependencies via rye add and rye sync.

Separate development and production environments.

Support importing a local workspace as a third‑party package.

The article also acknowledges the risk that Rye might become another niche tool, linking to the discussion "Should Rye Exist?" and the philosophy page for further reading.

1.1 Install rustup

Rye is built with Rust, so rustup must be installed first:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

After restarting the shell, verify the installation with cargo -V.

1.2 Install Rye

With cargo available, install Rye from its Git repository:

cargo install --git https://github.com/mitsuhiko/rye rye

Confirm the installation using rye -h. Add $HOME/.rye/shims to PATH to use the standalone Python interpreter directly.

1.3 Initialize a Rye project

Create a new project directory:

rye init test_rye
cd test_rye
tree

The resulting structure includes .git, .gitignore, .python-version, README.md, pyproject.toml, and a sample source file under src/test_rye/__init__.py.

1.4 Python version management

Pin a specific Python version for the workspace, e.g.:

# cpython@ can be omitted
rye pin [email protected]
rye pin 3.10.11

The rye pin command only updates the .python-version file; the actual interpreter is fetched when rye sync is run.

Use rye toolchain list to view installed versions and rye toolchain list --include-downloadable to see available downloads. Fetch a new version with rye toolchain fetch 3.8.16 and remove one with rye toolchain remove 3.8.16.

1.5 Add dependencies

Install packages (e.g., numpy) via:

rye add numpy
# add multiple packages
rye add six easydict
# specify version constraints
rye add "Flask>=2.0"
# add development‑only package
rye add --dev black
# add a package from GitHub
rye add Flask --git=https://github.com/pallets/flask
# add a local package
rye add My-Utility --path ./my-utility

These commands modify pyproject.toml; the actual installation occurs after rye sync.

1.6 Rye workflow

Initialize the project with rye init.

Commit the initial state with Git.

Pin the desired Python version.

Modify code and add required packages using rye add.

Run rye sync to install the interpreter and dependencies.

Test code with rye run python.

Optionally build a wheel using rye build and publish to PyPI with rye publish.

Rye handles dependency management; debugging and testing remain the developer’s responsibility. A dedicated shell can be opened with rye shell.

1.7 Install global Python tools

Some packages provide command‑line tools that are installed globally via: rye install black Run them with rye run black -h. Global tools reside in $HOME/.rye/shims and can be removed with rye uninstall black.

References

Rye documentation: https://mitsuhiko.github.io/rye

Armin Ronacher’s GitHub: https://github.com/mitsuhiko

PEP 668: https://peps.python.org/pep-0668

Discussion "Should Rye Exist?": https://github.com/mitsuhiko/rye/discussions/6

Rye philosophy page: https://mitsuhiko.github.io/rye/philosophy

PEP 711: https://peps.python.org/pep-0711