# Table of Contents - [Rye](#rye) - [Community - Rye](#community-rye) - [Introduction - Rye](#introduction-rye) - [Installation - Rye](#installation-rye) - [Philosophy - Rye](#philosophy-rye) - [Basics - Rye](#basics-rye) - [Changelog - Rye](#changelog-rye) - [Configuration - Rye](#configuration-rye) - [Python Project - Rye](#python-project-rye) - [Syncing and Locking - Rye](#syncing-and-locking-rye) - [Shims - Rye](#shims-rye) - [Building and Publishing - Rye](#building-and-publishing-rye) - [Rust Modules - Rye](#rust-modules-rye) - [Dependency Sources - Rye](#dependency-sources-rye) - [Dependencies - Rye](#dependencies-rye) - [Virtual Projects - Rye](#virtual-projects-rye) - [Workspaces - Rye](#workspaces-rye) - [Docker - Rye](#docker-rye) - [add - Rye](#add-rye) - [Overview - Rye](#overview-rye) - [build - Rye](#build-rye) - [config - Rye](#config-rye) - [install - Rye](#install-rye) - [fmt - Rye](#fmt-rye) - [init - Rye](#init-rye) - [make-req - Rye](#make-req-rye) - [lock - Rye](#lock-rye) - [lint - Rye](#lint-rye) - [pin - Rye](#pin-rye) - [publish - Rye](#publish-rye) - [remove - Rye](#remove-rye) - [show - Rye](#show-rye) - [run - Rye](#run-rye) - [sync - Rye](#sync-rye) - [test - Rye](#test-rye) - [Overview - Rye](#overview-rye) - [fetch - Rye](#fetch-rye) - [list - Rye](#list-rye) - [register - Rye](#register-rye) - [remove - Rye](#remove-rye) - [Overview - Rye](#overview-rye) - [install - Rye](#install-rye) - [Overview - Rye](#overview-rye) - [completion - Rye](#completion-rye) - [uninstall - Rye](#uninstall-rye) - [list - Rye](#list-rye) - [update - Rye](#update-rye) - [uninstall - Rye](#uninstall-rye) - [uninstall - Rye](#uninstall-rye) - [version - Rye](#version-rye) - [Toolchain Management - Rye](#toolchain-management-rye) - [Portable CPython - Rye](#portable-cpython-rye) - [Tools - Rye](#tools-rye) - [PyPy - Rye](#pypy-rye) - [Email Protection | Cloudflare](#email-protection-cloudflare) - [fetch - Rye](#fetch-rye) - [`list` - Rye](#-list-rye) - [FAQ - Rye](#faq-rye) --- # Rye [](https://github.com/astral-sh/rye/edit/main/docs/index.md "Edit this page") ![](static/logo-auto.svg) **Rye:** a Hassle-Free Python Experience ======================================== Note If you're getting started with Rye, consider [uv](https://github.com/astral-sh/uv) , the [successor project](https://lucumr.pocoo.org/2024/2/15/rye-grows-with-uv/) from the same maintainers. While Rye is actively maintained, uv offers a more stable and feature-complete experience, and is the recommended choice for new projects. Having trouble migrating? [Let us know what's missing.](https://github.com/astral-sh/rye/discussions/1342) Rye is a comprehensive project and package management solution for Python. Born from [its creator's](https://github.com/mitsuhiko) desire to establish a one-stop-shop for all Python users, Rye provides a unified experience to install and manages Python installations, `pyproject.toml` based projects, dependencies and virtualenvs seamlessly. It's designed to accommodate complex projects, monorepos and to facilitate global tool installations. Curious? [Watch an introduction](https://youtu.be/q99TYA7LnuA) . A hassle-free experience for Python developers at every level. [Star](https://github.com/astral-sh/rye) [Discuss](https://github.com/astral-sh/rye/discussions) [Sponsor](https://github.com/sponsors/mitsuhiko) Installation Instructions LinuxmacOSWindowsCompile Yourself 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. * [rye-x86\_64-linux.gz](https://github.com/astral-sh/rye/releases/latest/download/rye-x86_64-linux.gz) Intel/AMD (x86-64). * [rye-aarch64-linux.gz](https://github.com/astral-sh/rye/releases/latest/download/rye-aarch64-linux.gz) for ARM64. `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. * [rye-aarch64-macos.gz](https://github.com/astral-sh/rye/releases/latest/download/rye-aarch64-macos.gz) for Apple Silicon (M1/M2/M3) (ARM64). * [rye-x86\_64-macos.gz](https://github.com/astral-sh/rye/releases/latest/download/rye-x86_64-macos.gz) for Intel processors (x86-64). `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](guide/faq/) . * [rye-x86\_64-windows.exe](https://github.com/astral-sh/rye/releases/latest/download/rye-x86_64-windows.exe) for 64-bit (x86-64). * [rye-x86-windows.exe](https://github.com/astral-sh/rye/releases/latest/download/rye-x86-windows.exe) for 32-bit (x86). 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](https://github.com/astral-sh/rye/issues/468) . You need to have Rust and Cargo installed. If you don't have, you can use [rustup](https://rustup.rs/) to get them onto your machine. Afterwards you can install `Rye` via `cargo`: `cargo install --git https://github.com/astral-sh/rye rye` For the next steps or ways to customize the installation, head over to the detailed [installation](guide/installation/) guide. Back to top --- # Community - Rye [](https://github.com/astral-sh/rye/edit/main/docs/community.md "Edit this page") Community ========= Rye is a new project and feedback is greatly appreciated. Lots of it. Because of this there are various different ways in which you can engage with either the developer or other members of the community: * [Discussion Forum](https://github.com/astral-sh/rye/discussions) , to discuss the project on GitHub * [Discord](https://discord.gg/drbkcdtSbg) , for conversations with other developers in text form * [Issue Tracker](https://github.com/astral-sh/rye/issues) , if you run into bugs or have suggestions You can also reach out [via Twitter](https://twitter.com/mitsuhiko) or [Bluesky](https://bsky.app/profile/mitsuhiko.at) . Badges ------ Want to show that you are using Rye? Why not throw a badge into your project's `README.md`: `[![Rye](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/rye/main/artwork/badge.json)](https://rye.astral.sh)` ... or `README.rst`: `.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/rye/main/artwork/badge.json :target: https://rye.astral.sh :alt: Rye` ... or, as HTML: `Rye` [![Rye](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/rye/main/artwork/badge.json)](https://rye.astral.sh) Back to top --- # Introduction - Rye [](https://github.com/astral-sh/rye/edit/main/docs/guide/index.md "Edit this page") Introduction ============ Rye is still a very experimental tool, but this guide is here to help you get started. Before we dive into the installation and basic usage guide it's important for you to understand what Rye actually is. Rye is a one-stop-shop tool. The idea is that as a Python developer all you need to know is Rye, because Rye is your start into the experience. As a Rye user you do not even need to install Python yourself as Rye does this for you. This means to use Rye, you just need to install Rye, the rest is done by Rye itself. Once Rye is on your system, it can automatically install Python interpreters for you, install packages from package indexes, manage virtualenvs behind the scenes and more. Interested? Then head over to [Installation](installation/) to learn about how to get Rye onto your system. Once that is done, read the [Basics](basics/) to learn about how Rye can be used. Back to top --- # Installation - Rye [](https://github.com/astral-sh/rye/edit/main/docs/guide/installation.md "Edit this page") 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. LinuxmacOSWindowsCompile Yourself 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. * [rye-x86\_64-linux.gz](https://github.com/astral-sh/rye/releases/latest/download/rye-x86_64-linux.gz) Intel/AMD (x86-64). * [rye-aarch64-linux.gz](https://github.com/astral-sh/rye/releases/latest/download/rye-aarch64-linux.gz) for ARM64. `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. * [rye-aarch64-macos.gz](https://github.com/astral-sh/rye/releases/latest/download/rye-aarch64-macos.gz) for Apple Silicon (M1/M2/M3) (ARM64). * [rye-x86\_64-macos.gz](https://github.com/astral-sh/rye/releases/latest/download/rye-x86_64-macos.gz) for Intel processors (x86-64). `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](../faq/) . * [rye-x86\_64-windows.exe](https://github.com/astral-sh/rye/releases/latest/download/rye-x86_64-windows.exe) for 64-bit (x86-64). * [rye-x86-windows.exe](https://github.com/astral-sh/rye/releases/latest/download/rye-x86-windows.exe) for 32-bit (x86). 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](https://github.com/astral-sh/rye/issues/468) . You need to have Rust and Cargo installed. If you don't have, you can use [rustup](https://rustup.rs/) 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](../toolchains/) . To install a specific version download a binary directly [from GitHub](https://github.com/astral-sh/rye/releases) . 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. LinuxmacOSWindows 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. BashZSHFishNushellUnix ShellsWindows 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](../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: BashZshFishPowershellNuShell `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. LinuxmacOSWindows `export RYE_NO_AUTO_INSTALL=1` `export RYE_NO_AUTO_INSTALL=1` `set RYE_NO_AUTO_INSTALL=1` Back to top --- # Philosophy - Rye [](https://github.com/astral-sh/rye/edit/main/docs/philosophy.md "Edit this page") Philosophy and Vision ===================== Rye was built to solve [my](https://github.com/mitsuhiko) problems. Here is what was on my mind when I built it: * **Virtualenvs:** while I personally do not like virtualenvs that much, they are so widespread and have reasonable tooling support, so I chose this over `__pypackages__`. * **No Default Dependencies:** the virtualenvs when they come up are completely void of dependencies. Not even `pip` or `setuptools` are installed into it. Rye manages the virtualenv from outside the virtualenv. * **No Core Non-Standard Stuff:** Rye (with the exception of its own `tool` section in the `pyproject.toml`) uses standardized keys. That means it uses regular requirements as you would expect. It also does not use a custom lock file format and uses [`uv`](https://github.com/astral-sh/uv) . * **No Pip:** Rye uses [`uv`](https://github.com/astral-sh/uv) to manage dependencies, through `pyproject.toml` only. * **No System Python:** I can't deal with any more linux distribution weird Python installations or whatever mess there is on macOS. I used to build my own Pythons that are the same everywhere, now I use [indygreg's Python builds](https://github.com/indygreg/python-build-standalone) . Rye will automatically download and manage Python builds from there. No compiling, no divergence. * **Project Local Shims:** Rye maintains a `python` shim that auto discovers the current `pyproject.toml` and automatically operates below it. Just add the shims to your shell and you can run `python` and it will automatically always operate in the right project. What Could Be? -------------- There are a few shortcomings in the Python packaging world, largely as a result of lack of standardization. Here is what this project ran into over the years: * **No Python Binary Distributions:** CPython builds from python.org are completely inadequate. On some platforms you only get an .msi installer, on some you literally only get tarballs. The various Python distributions that became popular over the years are diverging greatly and cause all kinds of nonsense downstream. This is why this Project uses the indygreg standalone builds. I hope that with time someone will start distributing well maintained and reliable Python builds to replace the mess we are dealing with today. * **No Dev Dependencies:** Rye currently needs a custom section in the `pyproject.toml` to represent dev dependencies. There is no standard in the ecosystem for this. It really should be added. * **No Local Dependency Overlays:** There is no standard for how to represent local dependencies. Rust for this purpose has something like `{ path = "../foo" }` which allows both remote and local references to co-exist and it rewrites them on publish. * **No Exposed Pip:** pip is intentionally not exposed. If you install something into the virtualenv with pip, it disappears next time you sync. * **No Workspace Spec:** for monorepos and things of that nature, the Python ecosystem would need a definition of workspaces. Today that does not exist which forces every tool to come up with it's own solutions to this problem. * **No Basic Script Section:** There should be a standard in `pyproject.toml` to represent scripts like `rye` does in `rye.tools.scripts`. The Vision ---------- This describes of what I envision Python packaging and project management could look like in an ideal world: ### The Rust Experience Coming from a Rust environment there are two tools which work together: `rustup` and `cargo`. The first one of those is used to ensure that you have the correct Rust toolchain on your machine. Rust greatly prefers binary distributions of the language from the official website over external distributions. `cargo` is the main entry point to development in Rust. It acts as the tool to trigger test runs, start the build process, shell out to the documentation building tool, linters but also things such as workspace management, dependency management and package publishing. Crucially a very important aspect of the Rust development experience is the strong commitment to semver and the built-in support for it. This goes very deep. The resolver for instance will deduplicate matching dependencies throughout the graph. This means that if four libraries depend on `[[email protected]](/cdn-cgi/l/email-protection) `, they will all resolve to that dependency. However if another need arises for `[[email protected]](/cdn-cgi/l/email-protection) `, then it's possible for the dependency graph to result in both being loaded! The ecosystem greatly depends on this. For instance when a new major release is made of a very core library, in some cases extra care is taken to unify the now incompatible versions by re-exporting core types from the newer to the older version. Thus it's for instance possible for `[[email protected]](/cdn-cgi/l/email-protection) ` to depend on `[[email protected]](/cdn-cgi/l/email-protection) ` internally so it can make the transition easier. Additionally Rust heavily leverages lockfiles. Whenever you compile, the dependencies are locked in place and future builds reuse the same dependency versions unless you update. Most importantly though the Rust ecosystem has embraced `rustup` and `cargo` that the vast majority of people are using these tools on a daily basis. Even developers who pick other tools like buck, are still using `cargo` regularly. ### Going Python Rye wants to explore if such an experience is possible with Python. I believe it can! There is quite a lot of the ecosystem that can be leveraged for this purpose but there is even more that would need to be built. **Important note:** when you read "rye" in the context of the document it talks about what a potential tool like rye could be. It might as well be that one of the many tools that exist today, turn into that very tool that is described here. My sentiment is that unless "the one tool" can emerge in the Python world, the introduction of yet another tool might be a net-negative to the ecosystem. Plenty of tools have been created over the years, and unfortunately it hasn't been able to rally the majority of the Python community behind any tool. I do however believe it is possible. #### Bootstrapping Python I believe the right approach is that >95% of users get a Python distribution via `rye` and not to have `rye` pick up a system installed Python distribution. There are good reasons for using a system Python installation, but it should be the exception not the rule. Most importantly because a Python distribution that `rye` puts in place can be made to have reliable and simple rules that do not differ between systems. A huge cause of confusion and user frustration currently comes from Linux distribution specific patches on top of Python that break tools and change behavior, particularly in the python packaging ecosystem. Bootstrapping Python via an independent tool has other benefits as well. It for instance allows much easier cross-python version testing via tox or CI. **What needs to be done:** * Provide widely available Python builds, with largely standardized structure retrievable from the internet. [PEP 711](https://peps.python.org/pep-0711/) is a step in that direction. #### A Stronger Resolver Today there are a ton of different resolvers in the Python ecosystem. Pip has two, poetry has one, pdm has one, different independent Python and Rust resolvers exist on top of that. Resolvers are important, but unfortunately, there are both too many and too many issues with the existing ones. Here is what I believe a resolver needs to be able to accomplish: * **Allow resolving across markers:** most resolvers in the Python ecosystem today can only resolve for the current interpreter and platform (eg: pip, pip-tools). This means it cannot create a resolution that is equally valid for a different platform. In part this is a problem because of how environment markers in Python are defined. They allow a level of expressiveness that cannot be reflected by most tools, however a subset could be supported. * **Multi-version resolution support:** this is a bit foreshadowing, but I believe for a variety of reasons it needs to be possible for a resolver to not unify all requirements to a single version, but to support multiple independent resolutions across major versions of libraries. A future resolver should be able to permit `package==2.0` and `package==1.1` to both be resolved for different parts of the tree. * **Resolver API:** access to the resolver is important. For editor plugins, or custom tools it's always necessary to be able to resolve packages. For instance if you want something as trivial as "add latest supported version of 'flask' to my `pyproject.toml`" you need to be able to work with the resolver. * **Filters:** I strongly believe that a good resolver also needs a filter on top. For instance it must be possible for a developer to restrict the resolver to stay within the bounds of the target Python version and to never upgrade into a tree containing Python versions that are too new. Likewise for supply chain safety a resolver should be able to restrict itself to a set of vetted dependencies. **What needs to be done:** * Create a reusable resolver that can be used by multiple tools in the ecosystem. * Make the resolver work with the proposed metadata cache * Expose the resolver as API for multiple tools to use. * Add a policy layer into the resolver that can be used to filter down the dependencies before use. #### Metadata Caches Because of the rather simplistic nature of Python packages and package indexes a resolver will always be restricted by the metadata that it can reliably pull. This is particularly bad if the system needs to fall back to `sdist` uploads which in the worst case requires executing python code to determine the dependencies, and those dependencies might not even match on different platforms. However this is a solvable problem with sufficient caching, and with the right design for the cache, this cache could be shared. It might even be quite interesting for PyPI to serve up "fake" metadata records for popular sdist only packages to help resolvers. This might go a long way in improving the quality of the developer experience. **What needs to be done:** * Local metadata caches are added for the resolver to use * PyPI gains the ability to serve dependency meta data #### Lockfiles It's unclear if a standard can emerge for lock files given the different requirements, but a Python packaging solution needs to have support for these. There are a lot of different approaches to lockfiles today (poetry and pdm for instance have them) but it's not entirely clear to me that the way they are handled today is sufficiently pragmatic to enable a tool that is based on lockfiles to get majority adoption. The reason in part relates the suboptimal situation with resolvers (eg: large projects can take ten minutes or longer to dependency check in poetry), on the other hand however also because of the reality of how dependencies are currently declared. For instance certain libraries will "over" depend on third party libraries, even if they are not needed for a developer. These pulled in dependencies however will still influence the resolver. Most importantly a good lockfile also covers platforms other than the current developer's machine. This means that if a project supports Windows and Linux, the lockfile should be handling either dependency trees. This is what cargo accomplishes today, but cargo has a a much simpler problem to solve here because it has perfect access to package metadata which resolvers in Python do not have today. What is also problematic in Python is that certain parts of the dependency tree can be version dependent. In Rust a library A either depends on library B or it does not, but it does not depend on it conditional to a Python version. The total expressiveness of Python dependencies is challenging. The lack of good metadata access for the resolver combined with the ability to make dependencies optional conditional to the Python version is tricky by itself. The complexity however is compounded by the fact that the resolver needs to come to a solution that can only result in a single resolved version per package. **What needs to be done:** * Experiment with a restricted lock format that satisfies a subset of what markers provide today, that strikes a good balance. * Provide lockfile support as part of the resolver library. #### Upper Bounds & Multi Versioning Resolving Python dependencies is particularly challenging because a single solution must be found per package. A reason this works at all in the Python ecosystem is that most libraries do not set upper bounds. This means that they will be eagerly accepting future libraries even at the cost of not supporting them. That's largely possible because Python is a dynamic language and a lot of flexibility is usually possible here. However with increased utilization of type information in the Python world, and maybe with stronger desires for proper locking, it might be quite likely that upper version bounds become more common. Once that happens however, the Python ecosystem will quite quickly run into blocking future upgrades until the entire dependency graph has moved up which creates a lot of friction. Other ecosystems have solved this problem by strictly enforcing semver semantics onto packages and by permitting multiple semver incompatible libraries to be loaded simultaneously. While usually a library is only allowed to permit on a single version of a dependency, that dependency can exist in different versions throughout the dependency tree. In Python there is a perceived worry that this cannot be accomplished because of how site-packages, `PYTHONPATH` and `sys.modules` works. However I believe these to be solvable issues. On the one hand because `.pth` files can be used to completely change how the import system works, secondly because the `importlib.metadata` API is strong enough these days to allow a package to resolve it's own metadata. The combination of the two can be used to "redirect" imports in `sys.modules` and import statements to ensure that if a library imports a dependency of itself, it ends up with the right version. **What needs to be done:** * Add a new metadata key to `pyproject.toml` that declares that a package supports multi-versioning * Enforce semver semantics on multi-version dependencies * Provide an import hook that provides multi-version imports as part of Rye * Relax the resolver to permit multiple solutions for multi-version dependencies #### Workspaces and Local / Multi Path References With growing development teams one of the most frustrating experiences is the inability to break up a monolithic Python module into smaller modules without having to constantly publish minor versions to a package index. The way the Rust ecosystem deals with this issue is two-fold: on the one hand Rust supports workspaces natively. Workspaces share dependencies and the resolver results. The equivalent in Python would be that a workspace shares a virtualenv across all of the projects within in. The second way in which Rust solves this problem is to permit a dependency to both support declaration of the package name, index but also local reference. While also Rust does not permit a crate to be published to a package index with references to packages outside of the index, a separate rewrite step kicks in ahead of publish to clean out invalid dependency references. If no valid reference remains, the package will not publish. **What needs to be done:** * requirement declarations need to be expanded to support defining the name of the index where they can be found, and optional local path references. #### Every Project in a Virtualenv While virtualenv is not my favorite tool, it's the closest we have to a standard. I proposed that there is always one path for a virtualenv `.venv` and when Rye manages it, users should not interact with it manually. It's at that point rye's responsibility to manage it, and it shall manage it as if it was a throw-away, always re-creatable scratch-pad for dependencies. Preferably over time the structure of virtualenvs aligns between different Python versions (eg: Windows vs Linux) and the deeply nested `lib/py-ver/site-packages` structure is flattened out. **What needs to be done:** * Agree on a name for where managed virtualenvs are placed (eg: `.venv` in the workspace root) #### Dev and Tool Dependencies Another topic that is currently unresolved across tools in the ecosystem is how to work with dependencies that are not used in production. For instance it's quite common that a certain dependency really only matters on the developer's machine. Today pdm and some other tools have custom sections in the `pyproject.toml` file to mark development dependencies, but there is no agreement across tools on it. **What needs to be done:** There needs to be an agreed upon standard for all tools. [See this discussion](https://discuss.python.org/t/development-dependencies-in-pyproject-toml/26149/7) #### Opinionated Defaults Python against PEP-8's wishes just has too many ways in which things can be laid out. There should be a much stronger push towards encouraging common standards: **What needs to be done:** * Rye shall ship with the one true formatter * Rye shall ship with the one true linter * Rye shall always create a preferred folder structure for new projects * Rye shall loudly warn if `package-foo` does not provide a `package_foo` module ### Existing Tools Some of the existing tools in the ecosystem are close, and there is a good chance that some of these might be able to combine forces to create that one-true tool. I hope that there is enough shared interest, that we don't end up with three tools that all try to be Rye. Back to top --- # Basics - Rye [](https://github.com/astral-sh/rye/edit/main/docs/guide/basics.md "Edit this page") Basics ====== To use Rye you need to have a `pyproject.toml` based Python project. For this guide you can create one with [`rye init`](../commands/init/) which will create a new folder with a new project inside: `rye init my-project cd my-project` The following structure will be created: `. ├── .git ├── .gitignore ├── .python-version ├── README.md ├── pyproject.toml └── src └── my_project └── __init__.py` Good to Know The `init` command accepts a lot of options to customize what it generates. Run `rye init --help` to see all the options available in the version you have installed. A `pyproject.toml` is used to store metadata about your project as well as some Rye configuration. Most of Rye's commands will require a `pyproject.toml` to work. Note that Rye today does not support `setup.py` based projects. Note that when Rye initializes a project it also writes a `.python-version` file. This file contains the version number of the Python version that should be used for this project. It can be changed by running `rye pin`. For instance to tell Rye to use Python 3.10: `$ rye pin 3.10` First Sync ---------- Once that is done, you can use `rye sync` to get the first synchronization. After that, Rye will have created a virtualenv in `.venv` and written lockfiles into `requirements.lock` and `requirements-dev.lock`. `rye sync` The virtualenv that Rye manages is placed in `.venv` next to your `pyproject.toml`. The first time you run this you will notice that Rye automatically downloaded and installed a compatible CPython interpreter for you. If you have already another Python installation on your system it will not be used! For more information about this behavior [read about toolchains](../toolchains/) . You can activate and work with it as normal with one notable exception: the Python installation in it does not contain `pip`. If you have correctly installed Rye with the shims enabled, after the sync you can run `python` and you will automatically be operating in that virtualenv, even if it's not enabled. You can validate this by printing out `sys.prefix`: `python -c "import sys; print(sys.prefix)"` It will print out the full path to the managed virtualenv. Adding Dependencies ------------------- Use the `add` command to add dependencies to your project. `rye add "flask>=2.0"` Followed by `rye sync` to install the dependency into the virtual environment. If you want to add packages from custom indexes, you have to [configure the source](../sources/) first. Listing Dependencies -------------------- You can invoke `rye list` to get a dump of all installed dependencies of your project. Note that this only lists dependencies that are actually installed, so make sure to `sync` first. `rye list` Remove a Dependency ------------------- Use the `remove` command to remove a dependency from the project again. `rye remove flask` Working with the Project ------------------------ To run executables in the context of the virtualenv you can use the `run` command. For instance, to use `black`, add it to the project, sync the virtual environment, and run it over the current directory like this: `rye add black rye sync rye run black .` If you want to have the commands available directly you will need to activate the virtualenv like you do normally. To activate the virtualenv, use the standard methods: UnixWindows `. .venv/bin/activate` `.venv\Scripts\activate` To deactivate it again run `deactivate`: `deactivate` Inspecting the Project ---------------------- The `rye show` command can print out information about the project's state. By just running `rye show` you can see which Python version is used, where the virtualenv is located and more. `rye show` Executable projects ------------------- To generate a project that is aimed to provide an executable script, use `rye init --script`: `rye init --script my-project cd my-project` The following structure will be created: `. ├── .git ├── .gitignore ├── .python-version ├── README.md ├── pyproject.toml └── src └── my_project └── __init__.py └── __main__.py` The [`pyproject.toml`](../pyproject/) will be generated with a [`[project.scripts]`](../pyproject/#projectscripts) section containing a `my-project` script that points to the `main()` function of `__init__.py`. After you synchronized your changes, you can run the script with `rye run my-project`. `rye sync rye run my-project` Back to top --- # Changelog - Rye [](https://github.com/astral-sh/rye/edit/main/docs/changelog.md "Edit this page") Changelog ========= Here you can find all the released changes to Rye. If you want to also see the in-development changes that were not released yet, refer to the [CHANGELOG.md](https://github.com/astral-sh/rye/blob/main/CHANGELOG.md) file in the repository. 0.44.0 ------ Released on 2025-02-26. * Upgrade runners to `macos-14` by [@charliermarsh](https://github.com/charliermarsh "GitHub User: @charliermarsh") in https://github.com/astral-sh/rye/pull/1443 * Bump bundled Ruff version to 0.9.6 by [@catwell](https://github.com/catwell "GitHub User: @catwell") in https://github.com/astral-sh/rye/pull/1457 * Set Rust toolchain in `rust-toolchain.toml` by [@charliermarsh](https://github.com/charliermarsh "GitHub User: @charliermarsh") in https://github.com/astral-sh/rye/pull/1460 * Bump bundled uv version to v0.6.3 by [@github-actions](https://github.com/github-actions "GitHub User: @github-actions") in https://github.com/astral-sh/rye/pull/1445 0.43.0 ------ Released on 2024-12-09. * Fix compatible toolchain to allow Python 3.13 by [@PushUpek](https://github.com/PushUpek "GitHub User: @PushUpek") in https://github.com/astral-sh/rye/pull/1429 * Ignore free-threaded CPython builds by [@Alexis-D](https://github.com/Alexis-D "GitHub User: @Alexis-D") in https://github.com/astral-sh/rye/pull/1437 * Bump bundled Ruff version to v0.8.2 by [@charliermarsh](https://github.com/charliermarsh "GitHub User: @charliermarsh") in https://github.com/astral-sh/rye/pull/1440 * Add support for Python 3.9.21, 3.10.16, 3.11.11, 3.12.8, and 3.13.1 by [@github-actions](https://github.com/github-actions "GitHub User: @github-actions") in https://github.com/astral-sh/rye/pull/1439 * Upgrade bundled uv version to v0.5.7 by [@github-actions](https://github.com/github-actions "GitHub User: @github-actions") in https://github.com/astral-sh/rye/pull/1424 0.42.0 ------ Released on 2024-10-21. * Sync Python Releases by [@github-actions](https://github.com/github-actions "GitHub User: @github-actions") in https://github.com/astral-sh/rye/pull/1406 * Bump bundled Ruff version to v0.7.0 by [@charliermarsh](https://github.com/charliermarsh "GitHub User: @charliermarsh") in https://github.com/astral-sh/rye/pull/1419 * Bump bundled uv version to v0.4.25 by [@github-actions](https://github.com/github-actions "GitHub User: @github-actions") in https://github.com/astral-sh/rye/pull/1405 0.41.0 ------ Released on 2024-09-29. * Restore hash annotations in lockfile by [@charliermarsh](https://github.com/charliermarsh "GitHub User: @charliermarsh") in https://github.com/astral-sh/rye/pull/1403 * Upgrade bundled uv version to v0.4.17 by [@github-actions](https://github.com/github-actions "GitHub User: @github-actions") in https://github.com/astral-sh/rye/pull/1393 0.40.0 ------ Released on 2024-09-22. * Remove pip-tools support; use uv for all operations by [@nazq](https://github.com/nazq "GitHub User: @nazq") in https://github.com/astral-sh/rye/pull/1226 * Respect exclusions when generating hashes by [@charliermarsh](https://github.com/charliermarsh "GitHub User: @charliermarsh") in https://github.com/astral-sh/rye/pull/1357 * List all existing tool references on `rye toolchain remove` by [@soof-golan](https://github.com/soof-golan "GitHub User: @soof-golan") in https://github.com/astral-sh/rye/pull/1346 * Fix a few regex inefficiencies by [@InSyncWithFoo](https://github.com/InSyncWithFoo "GitHub User: @InSyncWithFoo") in https://github.com/astral-sh/rye/pull/1326 * Never modify or delete the virtualenv in `rye list` by [@bluss](https://github.com/bluss "GitHub User: @bluss") in https://github.com/astral-sh/rye/pull/1351 * Use `inspect_err` over `map_err` by [@charliermarsh](https://github.com/charliermarsh "GitHub User: @charliermarsh") in https://github.com/astral-sh/rye/pull/1385 * Upgrade bundled Python releases by [@github-actions](https://github.com/github-actions "GitHub User: @github-actions") in https://github.com/astral-sh/rye/pull/1379 * Upgrade bundled uv version to v0.4.15 by [@github-actions](https://github.com/github-actions "GitHub User: @github-actions") in https://github.com/astral-sh/rye/pull/1388 * Update bundled Ruff version to v0.6.7 by [@charliermarsh](https://github.com/charliermarsh "GitHub User: @charliermarsh") in https://github.com/astral-sh/rye/pull/1389 0.39.0 ------ Released on 2024-08-20. * Update Cargo dependencies by [@charliermarsh](https://github.com/charliermarsh "GitHub User: @charliermarsh") in https://github.com/astral-sh/rye/pull/1310 * Fix typo in `add.md` by [@mikkelam](https://github.com/mikkelam "GitHub User: @mikkelam") in https://github.com/astral-sh/rye/pull/1322 * Fix typo in FAQ by [@toadjaune](https://github.com/toadjaune "GitHub User: @toadjaune") in https://github.com/astral-sh/rye/pull/1330 * Update Python releases to include Python 3.12.4 by [@github-actions](https://github.com/github-actions "GitHub User: @github-actions") in https://github.com/astral-sh/rye/pull/1336 * Update bundled uv version to `v0.3.0` by [@github-actions](https://github.com/github-actions "GitHub User: @github-actions") in https://github.com/astral-sh/rye/pull/1332 0.38.0 ------ Released on 2024-08-01. * Fix `rye add` and `rye remove` to create proper `tool.rye` section for `--dev` and `--exclude` flags by [@flyaroundme](https://github.com/flyaroundme "GitHub User: @flyaroundme") in https://github.com/astral-sh/rye/pull/1256 * Fix `uninstall_cmd` on Windows by [@250h](https://github.com/250h "GitHub User: @250h") in https://github.com/astral-sh/rye/pull/1153 * Make rye run print script list to stdout by [@mitsuhiko](https://github.com/mitsuhiko "GitHub User: @mitsuhiko") in https://github.com/astral-sh/rye/pull/1268 * Always write `--index-url` before `--extra-index-url` by [@charliermarsh](https://github.com/charliermarsh "GitHub User: @charliermarsh") in https://github.com/astral-sh/rye/pull/1278 * Use case-insensitive comparison for detecting `rye.exe` by [@charliermarsh](https://github.com/charliermarsh "GitHub User: @charliermarsh") in https://github.com/astral-sh/rye/pull/1286 * Update Python releases to include stripped variants by [@github-actions](https://github.com/github-actions "GitHub User: @github-actions") in https://github.com/astral-sh/rye/pull/1280 * Fix documentation for readline license by [@3w36zj6](https://github.com/3w36zj6 "GitHub User: @3w36zj6") in https://github.com/astral-sh/rye/pull/1297 * Update bundled uv version to `v0.2.33` by [@github-actions](https://github.com/github-actions "GitHub User: @github-actions") in https://github.com/astral-sh/rye/pull/1303 * Update bundled pip to `v24.2.0` by [@charliermarsh](https://github.com/charliermarsh "GitHub User: @charliermarsh") in https://github.com/astral-sh/rye/pull/1304 0.37.0 ------ Released on 2024-07-20. * Fix verify-ssl option parsing by [@taki-d](https://github.com/taki-d "GitHub User: @taki-d") in https://github.com/astral-sh/rye/pull/1208 * Emit warning when asked to build a virtual project by [@nazq](https://github.com/nazq "GitHub User: @nazq") in https://github.com/astral-sh/rye/pull/1227 * Add short version `-d` for `rye remove --dev` by [@nikhilweee](https://github.com/nikhilweee "GitHub User: @nikhilweee") in https://github.com/astral-sh/rye/pull/1239 * Remove redundant alias information from CLI by [@piotrgredowski](https://github.com/piotrgredowski "GitHub User: @piotrgredowski") in https://github.com/astral-sh/rye/pull/1237 * Update bundled uv version to `v0.2.27` by [@github-actions](https://github.com/github-actions "GitHub User: @github-actions") in https://github.com/astral-sh/rye/pull/1232 * Update Python releases to include `3.12.4` by [@github-actions](https://github.com/github-actions "GitHub User: @github-actions") in https://github.com/astral-sh/rye/pull/1230 * Respect `.python-version` in Rye builds by [@charliermarsh](https://github.com/charliermarsh "GitHub User: @charliermarsh") in https://github.com/astral-sh/rye/pull/1250 * Update bundled Ruff version to `v0.5.4` by [@charliermarsh](https://github.com/charliermarsh "GitHub User: @charliermarsh") in https://github.com/astral-sh/rye/pull/1251 0.36.0 ------ Released on 2024-07-07. * Upgrade pyyaml to v6.0.1 by [@charliermarsh](https://github.com/charliermarsh "GitHub User: @charliermarsh") in https://github.com/astral-sh/rye/pull/1170 * Pass keyring-provider to uv sync and install by [@emarsden-iso](https://github.com/emarsden-iso "GitHub User: @emarsden-iso") in https://github.com/astral-sh/rye/pull/1183 * Add docs hint for packages on multiple indexes by [@dennisrall](https://github.com/dennisrall "GitHub User: @dennisrall") in https://github.com/astral-sh/rye/pull/1188 * Pass universal flag down to uv by [@lbowenwest](https://github.com/lbowenwest "GitHub User: @lbowenwest") in https://github.com/astral-sh/rye/pull/1186 * Use musl build for ARM Linux by [@charliermarsh](https://github.com/charliermarsh "GitHub User: @charliermarsh") in https://github.com/astral-sh/rye/pull/1192 * Bump uv to 0.2.22 by [@charliermarsh](https://github.com/charliermarsh "GitHub User: @charliermarsh") in https://github.com/astral-sh/rye/pull/1192 * Upgrade twine to v5.1.1 by [@charliermarsh](https://github.com/charliermarsh "GitHub User: @charliermarsh") in https://github.com/astral-sh/rye/pull/1199 0.35.0 ------ Released on 2024-06-24. * Enforce `--pre` when auto-syncing by [@charliermarsh](https://github.com/charliermarsh "GitHub User: @charliermarsh") in https://github.com/astral-sh/rye/pull/1107 * Move from `rye-up.com` to `rye.astral.sh` by [@charliermarsh](https://github.com/charliermarsh "GitHub User: @charliermarsh") in https://github.com/astral-sh/rye/pull/1113 * Fix install instructions on README.md for mac/linux by [@timothycrosley](https://github.com/timothycrosley "GitHub User: @timothycrosley") in https://github.com/astral-sh/rye/pull/1114 * Fix CLI deserialization of PowerShell (`powershell`) by [@charliermarsh](https://github.com/charliermarsh "GitHub User: @charliermarsh") in https://github.com/astral-sh/rye/pull/1125 * Add ability to specify option to generate hashes within pyproject.toml by [@asmith26](https://github.com/asmith26 "GitHub User: @asmith26") in https://github.com/astral-sh/rye/pull/1129 * Bump uv to 0.2.13 by [@charliermarsh](https://github.com/charliermarsh "GitHub User: @charliermarsh") in https://github.com/astral-sh/rye/pull/1123 * Improve `config.toml` error messages by [@zys864](https://github.com/zys864 "GitHub User: @zys864") in https://github.com/astral-sh/rye/pull/1155 0.34.0 ------ Released on 2024-05-20. * Add nushell completion support by [@MilesCranmer](https://github.com/MilesCranmer "GitHub User: @MilesCranmer") in https://github.com/astral-sh/rye/pull/1030 * Use uv in rye build when enabled by [@bluss](https://github.com/bluss "GitHub User: @bluss") in https://github.com/astral-sh/rye/pull/978 * Add short version add -d for rye add --dev by [@bluss](https://github.com/bluss "GitHub User: @bluss") in https://github.com/astral-sh/rye/pull/1044 * Flip uv to the default Rye backend by [@charliermarsh](https://github.com/charliermarsh "GitHub User: @charliermarsh") in https://github.com/astral-sh/rye/pull/1053 * Fix Rye not using user-chosen toolchain as default during installation by [@pjdon](https://github.com/pjdon "GitHub User: @pjdon") in https://github.com/astral-sh/rye/pull/1054 * Add keyring support for uv by [@emarsden-iso](https://github.com/emarsden-iso "GitHub User: @emarsden-iso") in https://github.com/astral-sh/rye/pull/1016 * Allow to generate lockfiles with hashes when using uv by [@mvaled](https://github.com/mvaled "GitHub User: @mvaled") in https://github.com/astral-sh/rye/pull/1070 * Bump ruff to 0.4.4 by [@davfsa](https://github.com/davfsa "GitHub User: @davfsa") in https://github.com/astral-sh/rye/pull/1075 * Fix TOML array formatting by [@my1e5](https://github.com/my1e5 "GitHub User: @my1e5") in https://github.com/astral-sh/rye/pull/1084 * Bump uv to 0.1.44 by [@charliermarsh](https://github.com/charliermarsh "GitHub User: @charliermarsh") in https://github.com/astral-sh/rye/pull/1085 * Discover cosmo-ified (`.com`) binaries on Windows by [@mataha](https://github.com/mataha "GitHub User: @mataha") in https://github.com/astral-sh/rye/pull/1091 * Write `use-uv = true` in no-prompt mode by [@charliermarsh](https://github.com/charliermarsh "GitHub User: @charliermarsh") in https://github.com/astral-sh/rye/pull/1098 0.33.0 ------ Released on 2024-04-24. * Ensure files created by `rye init`, such as `pyproject.toml` and initial python files end with a newline. [#979](https://github.com/astral-sh/rye/issues/979 "GitHub Issue astral-sh/rye #979") * Add `--refresh` argument on `-f`. [#994](https://github.com/astral-sh/rye/issues/994 "GitHub Issue astral-sh/rye #994") * Preserve trailing newline in templates. [#979](https://github.com/astral-sh/rye/issues/979 "GitHub Issue astral-sh/rye #979") * Update uv to 0.1.37. [#980](https://github.com/astral-sh/rye/issues/980 "GitHub Issue astral-sh/rye #980") * Allow comments in `.python-version`. [#1038](https://github.com/astral-sh/rye/issues/1038 "GitHub Issue astral-sh/rye #1038") * Update Python releases to include 3.12.3 et al. [#1022](https://github.com/astral-sh/rye/issues/1022 "GitHub Issue astral-sh/rye #1022") 0.32.0 ------ Released on 2024-03-29 * Update uv to 0.1.26. [#924](https://github.com/astral-sh/rye/issues/924 "GitHub Issue astral-sh/rye #924") * Always create `.gitignore` file in `rye init`. [#919](https://github.com/astral-sh/rye/issues/919 "GitHub Issue astral-sh/rye #919") * Prevent `rye fetch --force` from removing a target directory that is not a Python installation. [#921](https://github.com/astral-sh/rye/issues/921 "GitHub Issue astral-sh/rye #921") * `rye list` always prints the currently installed packages even this project is not managed by Rye. [#940](https://github.com/astral-sh/rye/issues/940 "GitHub Issue astral-sh/rye #940") * Fix error on using -v or -q with `rye fmt` or `rye lint`. [#959](https://github.com/astral-sh/rye/issues/959 "GitHub Issue astral-sh/rye #959") * Fix rye fetch detection of registered toolchain. [#931](https://github.com/astral-sh/rye/issues/931 "GitHub Issue astral-sh/rye #931") * Ignore build-system configuration for virtual projects. [#929](https://github.com/astral-sh/rye/issues/929 "GitHub Issue astral-sh/rye #929") 0.31.0 ------ Released on 2024-03-22 * Update uv to 0.1.23. [#916](https://github.com/astral-sh/rye/issues/916 "GitHub Issue astral-sh/rye #916") * Allow `rye publish` working outside of project. [#910](https://github.com/astral-sh/rye/issues/910 "GitHub Issue astral-sh/rye #910") * `rye test --quiet` no longer implies `--no-capture`. [#915](https://github.com/astral-sh/rye/issues/915 "GitHub Issue astral-sh/rye #915") * Rye now can be used to fetch Python installations even when not using Rye and build infos are no longer included by default. This means that rather than having interpreters at `~/.rye/py/[[email protected]](/cdn-cgi/l/email-protection) /install/bin/python3` it will now reside at `~/.rye/py/[[email protected]](/cdn-cgi/l/email-protection) /bin/python3`. [#917](https://github.com/astral-sh/rye/issues/917 "GitHub Issue astral-sh/rye #917") * Installer now recommends `uv` over `pip-tools`. [#918](https://github.com/astral-sh/rye/issues/918 "GitHub Issue astral-sh/rye #918") 0.30.0 ------ Released on 2024-03-19 * Update uv to 0.1.21. [#884](https://github.com/astral-sh/rye/issues/884 "GitHub Issue astral-sh/rye #884") , [#890](https://github.com/astral-sh/rye/issues/890 "GitHub Issue astral-sh/rye #890") , [#904](https://github.com/astral-sh/rye/issues/904 "GitHub Issue astral-sh/rye #904") * Fix incorrect flag passing of `rye test` `-q` and `-v`. [#880](https://github.com/astral-sh/rye/issues/880 "GitHub Issue astral-sh/rye #880") * Rye now loads `.env` files. This applies both for Rye's own use of environment variables but also to scripts launched via `run`. [#894](https://github.com/astral-sh/rye/issues/894 "GitHub Issue astral-sh/rye #894") * Fix `rye add m --path ./m` causing a panic on windows. [#897](https://github.com/astral-sh/rye/issues/897 "GitHub Issue astral-sh/rye #897") 0.29.0 ------ Released on 2024-03-11 * Updated to `uv` 0.1.17. [#850](https://github.com/astral-sh/rye/issues/850 "GitHub Issue astral-sh/rye #850") , [#867](https://github.com/astral-sh/rye/issues/867 "GitHub Issue astral-sh/rye #867") * Trap panics and silence bad pipe errors. [#862](https://github.com/astral-sh/rye/issues/862 "GitHub Issue astral-sh/rye #862") * Updating `rye` will now also ensure that the self-venv is updated. Previously this was deferred until the next `sync`. [#863](https://github.com/astral-sh/rye/issues/863 "GitHub Issue astral-sh/rye #863") * The `self update` command now accepts `--branch`. [#864](https://github.com/astral-sh/rye/issues/864 "GitHub Issue astral-sh/rye #864") * Fixed an issue that caused pip-tools to not update. [#865](https://github.com/astral-sh/rye/issues/865 "GitHub Issue astral-sh/rye #865") * Updates `build` and `certifi`. [#866](https://github.com/astral-sh/rye/issues/866 "GitHub Issue astral-sh/rye #866") 0.28.0 ------ Released on 2024-03-07 * `--skip-existing` is now available with Rye's `publish` command. [#831](https://github.com/astral-sh/rye/issues/831 "GitHub Issue astral-sh/rye #831") * Bumped `uv` to 0.1.15. [#760](https://github.com/astral-sh/rye/issues/760 "GitHub Issue astral-sh/rye #760") , [#820](https://github.com/astral-sh/rye/issues/820 "GitHub Issue astral-sh/rye #820") , [#837](https://github.com/astral-sh/rye/issues/837 "GitHub Issue astral-sh/rye #837") * Bumped `ruff` to 0.3.0. [#821](https://github.com/astral-sh/rye/issues/821 "GitHub Issue astral-sh/rye #821") * The `init` command now generates a script with the name of the project rather than `hello`. [#801](https://github.com/astral-sh/rye/issues/801 "GitHub Issue astral-sh/rye #801") * Retain markers when adding dependencies with features when uv is used. [#807](https://github.com/astral-sh/rye/issues/807 "GitHub Issue astral-sh/rye #807") * Fixed a bug that caused repeated syncs not to recall all previous options. [#830](https://github.com/astral-sh/rye/issues/830 "GitHub Issue astral-sh/rye #830") * Report `self-python` version in `--version`. [#843](https://github.com/astral-sh/rye/issues/843 "GitHub Issue astral-sh/rye #843") * Fixes a bug where `rye config` would not create the `RYE_HOME` folder if needed. [#844](https://github.com/astral-sh/rye/issues/844 "GitHub Issue astral-sh/rye #844") * `rye add` now retains version and URL for the requirements when `uv` is used. [#846](https://github.com/astral-sh/rye/issues/846 "GitHub Issue astral-sh/rye #846") * Added a `rye test` command which invokes `pytest`. [#847](https://github.com/astral-sh/rye/issues/847 "GitHub Issue astral-sh/rye #847") 0.27.0 ------ Released on 2024-02-26 * rye now uses `uv` to bootstrap its internal packages and tools. [#754](https://github.com/astral-sh/rye/issues/754 "GitHub Issue astral-sh/rye #754") * rye no longer fails if an incorrect `VIRTUAL_ENV` environment variable is exported. [#766](https://github.com/astral-sh/rye/issues/766 "GitHub Issue astral-sh/rye #766") * Added latest Python builds. [#771](https://github.com/astral-sh/rye/issues/771 "GitHub Issue astral-sh/rye #771") * When `uv` is used the prompt is now set to the project name. [#773](https://github.com/astral-sh/rye/issues/773 "GitHub Issue astral-sh/rye #773") * Allow `rye fetch --force` to force re-fetch a downloaded toolchain. [#778](https://github.com/astral-sh/rye/issues/778 "GitHub Issue astral-sh/rye #778") * Fixed a panic when adding a package to a virtual project. [#783](https://github.com/astral-sh/rye/issues/783 "GitHub Issue astral-sh/rye #783") * Bumped `uv` to 0.1.11. [#790](https://github.com/astral-sh/rye/issues/790 "GitHub Issue astral-sh/rye #790") 0.26.0 ------ Released on 2024-02-23 * `init` now supports `--script` and `--lib` to generate a script or library project. [#738](https://github.com/astral-sh/rye/issues/738 "GitHub Issue astral-sh/rye #738") * Fixed `rye config --show-path` abort with an error. [#706](https://github.com/astral-sh/rye/issues/706 "GitHub Issue astral-sh/rye #706") * Bumped `uv` to 0.1.9. [#719](https://github.com/astral-sh/rye/issues/719 "GitHub Issue astral-sh/rye #719") , [#740](https://github.com/astral-sh/rye/issues/740 "GitHub Issue astral-sh/rye #740") , [#746](https://github.com/astral-sh/rye/issues/746 "GitHub Issue astral-sh/rye #746") * Bumped `ruff` to 0.2.2. [#700](https://github.com/astral-sh/rye/issues/700 "GitHub Issue astral-sh/rye #700") * Prevent `rye toolchain remove` from removing the currently active toolchain. [#693](https://github.com/astral-sh/rye/issues/693 "GitHub Issue astral-sh/rye #693") * Sync latest PyPy releases. [#683](https://github.com/astral-sh/rye/issues/683 "GitHub Issue astral-sh/rye #683") * Fixes an issue where when `uv` is enabled, `add` did not honor custom sources. [#720](https://github.com/astral-sh/rye/issues/720 "GitHub Issue astral-sh/rye #720") * When `uv` is enabled, rye will now automatically sync on `add` and `remove`. [#677](https://github.com/astral-sh/rye/issues/677 "GitHub Issue astral-sh/rye #677") * Rename `rye tools list` flags: `-i, --include-scripts` to `-s, --include-scripts` and `-v, --version-show` to `-v, --include-version`. [#722](https://github.com/astral-sh/rye/issues/722 "GitHub Issue astral-sh/rye #722") 0.25.0 ------ Released on 2024-02-19 * Improved the error message if `config` is invoked without arguments. [#660](https://github.com/astral-sh/rye/issues/660 "GitHub Issue astral-sh/rye #660") * Bump `uv` to 0.1.5. [#665](https://github.com/astral-sh/rye/issues/665 "GitHub Issue astral-sh/rye #665") , [#675](https://github.com/astral-sh/rye/issues/675 "GitHub Issue astral-sh/rye #675") , [#698](https://github.com/astral-sh/rye/issues/698 "GitHub Issue astral-sh/rye #698") * When `uv` is enabled, `rye add` now uses `uv` instead of `unearth` internally. [#667](https://github.com/astral-sh/rye/issues/667 "GitHub Issue astral-sh/rye #667") * The installer now has slightly better wording for what the shims are doing. [#669](https://github.com/astral-sh/rye/issues/669 "GitHub Issue astral-sh/rye #669") * `uv` can now also be enabled on windows. [#675](https://github.com/astral-sh/rye/issues/675 "GitHub Issue astral-sh/rye #675") * Removed the unsupported and un-used `arch` parameter from `fetch`. [#681](https://github.com/astral-sh/rye/issues/681 "GitHub Issue astral-sh/rye #681") * Fixed the `-q` parameter not working for the `init` command. [#686](https://github.com/astral-sh/rye/issues/686 "GitHub Issue astral-sh/rye #686") * `rye tools list` shows broken tools if the toolchain was removed. [#692](https://github.com/astral-sh/rye/issues/692 "GitHub Issue astral-sh/rye #692") * Configure the ruff cache directory to be located within the workspace root. [#689](https://github.com/astral-sh/rye/issues/689 "GitHub Issue astral-sh/rye #689") * Use default toolchain to install tools. [#666](https://github.com/astral-sh/rye/issues/666 "GitHub Issue astral-sh/rye #666") * `rye --version` now shows if `uv` is enabled. [#699](https://github.com/astral-sh/rye/issues/699 "GitHub Issue astral-sh/rye #699") 0.24.0 ------ Released on 2024-02-15 * Added new `rye list` command and deprecated `rye show --installed-deps` which it replaces. [#656](https://github.com/astral-sh/rye/issues/656 "GitHub Issue astral-sh/rye #656") * Added experimental support for `uv`. [#657](https://github.com/astral-sh/rye/issues/657 "GitHub Issue astral-sh/rye #657") 0.23.0 ------ Released on 2024-02-13 * When `behavior.venv-mark-sync-ignore` is set to `false` and the file system does not support extended attributes, no longer will a warning be printed. [#633](https://github.com/astral-sh/rye/issues/633 "GitHub Issue astral-sh/rye #633") * Fixed a bug that caused warnings about unsupported operations to be shown on Linux. [#634](https://github.com/astral-sh/rye/issues/634 "GitHub Issue astral-sh/rye #634") * The venv sync marker is now only updated when a new virtualenv is created. [#638](https://github.com/astral-sh/rye/issues/638 "GitHub Issue astral-sh/rye #638") * Lockfiles now contain annotations. [#643](https://github.com/astral-sh/rye/issues/643 "GitHub Issue astral-sh/rye #643") 0.22.0 ------ Released on 2024-02-09 * Virtual envs managed by Rye will now by default be marked to not sync to known cloud storage systems (Dropbox and iCloud). [#589](https://github.com/astral-sh/rye/issues/589 "GitHub Issue astral-sh/rye #589") * Fixed a bug where pip-tools sometimes did not get initialized. [#596](https://github.com/astral-sh/rye/issues/596 "GitHub Issue astral-sh/rye #596") * Rye now prefers installed toolchains over newer latest toolchains unless a precise pin is used. [#598](https://github.com/astral-sh/rye/issues/598 "GitHub Issue astral-sh/rye #598") * Removed the non functional `shell` command. [#602](https://github.com/astral-sh/rye/issues/602 "GitHub Issue astral-sh/rye #602") * Upgraded internal unearth dependency which resolved an issue where `rye add tensorflow` would not work. [#614](https://github.com/astral-sh/rye/issues/614 "GitHub Issue astral-sh/rye #614") * The installer now supports `RYE_TOOLCHAIN_VERSION`. [#606](https://github.com/astral-sh/rye/issues/606 "GitHub Issue astral-sh/rye #606") * `rye init` will no longer create packages with leading digits. [#616](https://github.com/astral-sh/rye/issues/616 "GitHub Issue astral-sh/rye #616") * Rye now statically links `vcruntime` on Windows which no longer requires the vs redist to be installed. [#622](https://github.com/astral-sh/rye/issues/622 "GitHub Issue astral-sh/rye #622") * `rye show` now prints out which sources are configured for a project. [#631](https://github.com/astral-sh/rye/issues/631 "GitHub Issue astral-sh/rye #631") 0.21.0 ------ Released on 2024-02-03 * `rye fetch` now is able to fetch impliciit version in all cases. Previously global shims were not properly defaulted which required the user to be explicit with the fetch request. [#574](https://github.com/astral-sh/rye/issues/574 "GitHub Issue astral-sh/rye #574") * The rye installer now prompts for the default toolchain version if global shims are enabled. [#576](https://github.com/astral-sh/rye/issues/576 "GitHub Issue astral-sh/rye #576") * The internal Python version was bumped to 3.12. [#576](https://github.com/astral-sh/rye/issues/576 "GitHub Issue astral-sh/rye #576") * The installer now can automatically add Rye to `PATH` on most UNIX environments. [#580](https://github.com/astral-sh/rye/issues/580 "GitHub Issue astral-sh/rye #580") 0.20.0 ------ Released on 2024-02-01 * Improved the error message when an update could not be performed because files are in use. [#550](https://github.com/astral-sh/rye/issues/550 "GitHub Issue astral-sh/rye #550") * Rye now supports virtual projects. These are themselves not installed into the virtualenv but their dependencies are. [#551](https://github.com/astral-sh/rye/issues/551 "GitHub Issue astral-sh/rye #551") * Update the Python internals (python external dependencies) to new versions. [#553](https://github.com/astral-sh/rye/issues/553 "GitHub Issue astral-sh/rye #553") * Update to newer versions of pip tools. For Python 3.7 `6.14.0` is used, for new Python versions `7.3.0` is used. [#554](https://github.com/astral-sh/rye/issues/554 "GitHub Issue astral-sh/rye #554") * Added `rye fmt` and `rye lint` commands to format and lint with the help of Ruff. [#555](https://github.com/astral-sh/rye/issues/555 "GitHub Issue astral-sh/rye #555") * Restore cursor state on Ctrl-C. This fixes some issues where in rare cases the cursor would disappear even after shutting down rye. [#564](https://github.com/astral-sh/rye/issues/564 "GitHub Issue astral-sh/rye #564") * Upon installation Rye now prompts if global shims should be enabled. [#566](https://github.com/astral-sh/rye/issues/566 "GitHub Issue astral-sh/rye #566") * Add a warning about bugs to the `shell` command until the behavior has been fixed. [#567](https://github.com/astral-sh/rye/issues/567 "GitHub Issue astral-sh/rye #567") 0.19.0 ------ Released on 2024-01-21 * Improved the behavior of `rye fetch`. When invoked without arguments it will now try to fetch the version of the requested Python interpreter. Specifically this combining `pin` and `fetch` work in a much simplified manner. [#545](https://github.com/astral-sh/rye/issues/545 "GitHub Issue astral-sh/rye #545") * Fixed an issue where `rye init` would pin a much too specific version in the `.python-version` file that is generated. [#545](https://github.com/astral-sh/rye/issues/545 "GitHub Issue astral-sh/rye #545") * On Windows the `PATH` is now automatically adjusted on install and uninstall. This means that manually adding the rye folder to the search path is no longer necessary. [#483](https://github.com/astral-sh/rye/issues/483 "GitHub Issue astral-sh/rye #483") * Fixed a regression in 0.18 that caused the `add` command to fail. [#547](https://github.com/astral-sh/rye/issues/547 "GitHub Issue astral-sh/rye #547") 0.18.0 ------ Released on 2024-01-20 * Incorporate new Python builds. [#535](https://github.com/astral-sh/rye/issues/535 "GitHub Issue astral-sh/rye #535") * Disable revocation checks on windows to support corporate MITM proxies. [#537](https://github.com/astral-sh/rye/issues/537 "GitHub Issue astral-sh/rye #537") * Detect when a virtualenv relocates and automatically re-create it on sync. [#538](https://github.com/astral-sh/rye/issues/538 "GitHub Issue astral-sh/rye #538") * Added `lock --with-sources`, `sync --with-sources` and the new `rye.tool.lock-with-sources` config. Passing this will ensure that source references are included in the lock files. [#540](https://github.com/astral-sh/rye/issues/540 "GitHub Issue astral-sh/rye #540") * When using global python shims, the `.python-version` file is now correctly picked up in all cases. [#541](https://github.com/astral-sh/rye/issues/541 "GitHub Issue astral-sh/rye #541") * Added a helpful message if someone attempts to run the non existing `rye list` command. At a later point there should be a real listing command that can print out the dependencies. Today the only option is the `--installed-deps` option on the `show` command which spits out dependencies in the format of the lockfile. [#543](https://github.com/astral-sh/rye/issues/543 "GitHub Issue astral-sh/rye #543") * The installer will no longer attempt to symlink targets which are not valid executables on the platform. This works around some issues with Packages that would prevent to install such as `changedetection.io`. [#542](https://github.com/astral-sh/rye/issues/542 "GitHub Issue astral-sh/rye #542") 0.17.0 ------ Released on 2024-01-15 * Fixed default generated script reference. [#527](https://github.com/astral-sh/rye/issues/527 "GitHub Issue astral-sh/rye #527") * Correctly fall back to home folder if HOME is unset. [#533](https://github.com/astral-sh/rye/issues/533 "GitHub Issue astral-sh/rye #533") 0.16.0 ------ Released on 2023-12-17 * By default a script with the name of the project is now also configured. [#519](https://github.com/astral-sh/rye/issues/519 "GitHub Issue astral-sh/rye #519") * Rye now configures hatchling better in `rye init` so that it works with hatchling 1.19 and later. [#521](https://github.com/astral-sh/rye/issues/521 "GitHub Issue astral-sh/rye #521") * Rye now detects the dummy Python shim that starts the windows store and refuses to consider it. [#486](https://github.com/astral-sh/rye/issues/486 "GitHub Issue astral-sh/rye #486") 0.15.2 ------ Released on 2023-10-04 * Fixed the updater not replacing the python shim correctly on Linux. 0.15.1 ------ Released on 2023-10-03 * Fixed the updater not replacing the python3 shim correctly. 0.15.0 ------ Released on 2023-10-03 * Added support for Python 3.12. [#462](https://github.com/astral-sh/rye/issues/462 "GitHub Issue astral-sh/rye #462") 0.14.0 ------ Released on 2023-10-01 * Add support for fetching alternative CPU architectures. [#447](https://github.com/astral-sh/rye/issues/447 "GitHub Issue astral-sh/rye #447") * The order of git submodule initialization was changed. This improves the automatic author detection when `includeIf` is used. [#443](https://github.com/astral-sh/rye/issues/443 "GitHub Issue astral-sh/rye #443") * The linux shim installer code will no longer fall back to symlinks when a hardlink cannot be created. This is done as a symlinked shim will not ever function correctly on Linux. This prevents the shim executables like `python` to instead act as if they are `rye`. The fallback behavior is now to copy the executable instead. [#441](https://github.com/astral-sh/rye/issues/441 "GitHub Issue astral-sh/rye #441") * The installer now detects `fish` and will spit out additional instructions for configuring the shell. * Fix the wrong behavior when bump version. [#454](https://github.com/astral-sh/rye/issues/454 "GitHub Issue astral-sh/rye #454") 0.13.0 ------ Released on 2023-08-29 * Add a `python3` shim on windows. Previously entering `python3` in the command line would always bring up the windows store python proxy even when global shims were enabled. As virtualenvs do not support the `python3` executable on windows, the internal shim handling is now also changed so that trying to launch `python3` will fall back to `python`. This makes it possible to run `maturin build`. * Add `maturin` build command to start a new maturin PyO3 project. 0.12.0 ------ Released on 2023-08-27 * Improve handling of the pth files for TCL on pypy. [#409](https://github.com/astral-sh/rye/issues/409 "GitHub Issue astral-sh/rye #409") * The `rye tools list` command now accepts `-v` to also print out the versions of the installed tools. [#396](https://github.com/astral-sh/rye/issues/396 "GitHub Issue astral-sh/rye #396") * Fixed parsing of versions by `rye version`. [#397](https://github.com/astral-sh/rye/issues/397 "GitHub Issue astral-sh/rye #397") * Improved the help message for `rye init`. [#401](https://github.com/astral-sh/rye/issues/401 "GitHub Issue astral-sh/rye #401") * The email address now defaults to a syntactically valid email address if not known to prevent errors with some build tools. * Added new Python versions. * The rye installer now detects `NOEXEC` temporary folders and prints out a more helpful error message. [#394](https://github.com/astral-sh/rye/issues/394 "GitHub Issue astral-sh/rye #394") * Fixed an issue where the author email was incorrectly detected. [#382](https://github.com/astral-sh/rye/issues/382 "GitHub Issue astral-sh/rye #382") * The prompt of new virtualenvs is now set to the project name. [#383](https://github.com/astral-sh/rye/issues/383 "GitHub Issue astral-sh/rye #383") 0.11.0 ------ Released on 2023-07-18 * Added new Python versions. * Added a new config key `default.author` to configure the default author that should be set. This overrides the default author that is normally loaded from the git config. [#377](https://github.com/astral-sh/rye/issues/377 "GitHub Issue astral-sh/rye #377") * When importing with `rye init` and no `src` folder exists, it will not be created. [#375](https://github.com/astral-sh/rye/issues/375 "GitHub Issue astral-sh/rye #375") * Added support for `shell` command on Windows. [#363](https://github.com/astral-sh/rye/issues/363 "GitHub Issue astral-sh/rye #363") * Pin down pip to an older version to avoid issues with an incompatible `pip-tools` version. This does not yet update pip-tools to 7.0 as there are significant regressions in 7.x. [#374](https://github.com/astral-sh/rye/issues/374 "GitHub Issue astral-sh/rye #374") * The `version` command can show dynamic versions now. [#355](https://github.com/astral-sh/rye/issues/355 "GitHub Issue astral-sh/rye #355") * `rye add` now properly checks some incompatible argument combinations. [#347](https://github.com/astral-sh/rye/issues/347 "GitHub Issue astral-sh/rye #347") * There is now more toolchain validation. This better supports cases where rye was interrupted during sync. [#351](https://github.com/astral-sh/rye/issues/351 "GitHub Issue astral-sh/rye #351") 0.10.0 ------ Released on 2023-07-07 * Fixed a bug with `rye init` not operating correctly due to a argument conflict. [#346](https://github.com/astral-sh/rye/issues/346 "GitHub Issue astral-sh/rye #346") * Scripts now support a PDM style `call` script type. [#345](https://github.com/astral-sh/rye/issues/345 "GitHub Issue astral-sh/rye #345") * The `init` command is now capable of importing existing projects. [#265](https://github.com/astral-sh/rye/issues/265 "GitHub Issue astral-sh/rye #265") * Fixed the global shim behavior on Windows. [#344](https://github.com/astral-sh/rye/issues/344 "GitHub Issue astral-sh/rye #344") 0.9.0 ----- Released on 2023-06-21 * The internal Rye Python version is now 3.11. * Rye now emits most messages, most of the time to stdout rather than stderr. [#342](https://github.com/astral-sh/rye/issues/342 "GitHub Issue astral-sh/rye #342") * `rye add` now accepts `--pin` to let one override the type of pin to use. [#341](https://github.com/astral-sh/rye/issues/341 "GitHub Issue astral-sh/rye #341") * Added `rye config` to read and manipulate the `config.toml` file. [#339](https://github.com/astral-sh/rye/issues/339 "GitHub Issue astral-sh/rye #339") * Added support for the new `behavior.global-python` flag which turns on global Python shimming. When enabled then the `python` shim works even outside of Rye managed projects. Additionally the shim (when run outside of Rye managed projects) supports a special first parameter `+VERSION` which requests a specific version of Python (eg: `python +3.8` to request Python 3.8). [#336](https://github.com/astral-sh/rye/issues/336 "GitHub Issue astral-sh/rye #336") * Renamed the config key `default.dependency_operator` to `default.dependency-operator` and `behavior.force_rye_managed` to `behavior.force-rye-managed`. [#338](https://github.com/astral-sh/rye/issues/338 "GitHub Issue astral-sh/rye #338") 0.8.0 ----- Released on 2023-06-18 * Rye for now prefers `>=` over `~=` for newly added dependencies. * The workspace member declaration is now platform independent. If `members` is now explicitly set to an empty list it will not fall back to auto discovery. [#331](https://github.com/astral-sh/rye/issues/331 "GitHub Issue astral-sh/rye #331") * `rye add` now pins versions with `==` instead of `~=` when the version of the package does not use at least two components. This means that for instance it will now correctly use `openai-whisper==20230314` rather than `openai-whisper~=20230314` which is not actually satisfiable. [#328](https://github.com/astral-sh/rye/issues/328 "GitHub Issue astral-sh/rye #328") * `rye install` now lets you install dependencies into the tool's virtualenv during installation that are undeclared via the new `--extra-requirement` option. [#326](https://github.com/astral-sh/rye/issues/326 "GitHub Issue astral-sh/rye #326") * Improved handling of relative path installations by setting `PROJECT_ROOT` the same way as PDM does. [#321](https://github.com/astral-sh/rye/issues/321 "GitHub Issue astral-sh/rye #321") * Workspaces will now never discover `pyproject.toml` files in any dot directories. (Name starting with `.`) [#329](https://github.com/astral-sh/rye/issues/329 "GitHub Issue astral-sh/rye #329") * Fixed `rye build` not working correctly on Windows. [#327](https://github.com/astral-sh/rye/issues/327 "GitHub Issue astral-sh/rye #327") 0.7.0 ----- Released on 2023-06-12 * `rye sync` and `rye lock` now accept `--pyproject`. [#296](https://github.com/astral-sh/rye/issues/296 "GitHub Issue astral-sh/rye #296") * Added JSON output to `rye toolchain list` by adding `--format=json`. [#306](https://github.com/astral-sh/rye/issues/306 "GitHub Issue astral-sh/rye #306") * `rye version` can bump version by `--bump` option now. [#298](https://github.com/astral-sh/rye/issues/298 "GitHub Issue astral-sh/rye #298") * Fixed members not handled correctly in workspaces. [#300](https://github.com/astral-sh/rye/issues/300 "GitHub Issue astral-sh/rye #300") * Add `--clean` for `build` command. [#297](https://github.com/astral-sh/rye/issues/297 "GitHub Issue astral-sh/rye #297") * Fixed an issue where pip was not invoked from the right working directory causing issues for workspace installations. [#292](https://github.com/astral-sh/rye/issues/292 "GitHub Issue astral-sh/rye #292") * `rye init` now accepts `--private` to set the `Private :: Do Not Upload` classifier that prevents uploads to PyPI. [#291](https://github.com/astral-sh/rye/issues/291 "GitHub Issue astral-sh/rye #291") 0.6.0 ----- Released on 2023-06-03 * Add `version` subcommand for rye. [#285](https://github.com/astral-sh/rye/issues/285 "GitHub Issue astral-sh/rye #285") * Fixed `rye pin` pinning the wrong version. [#288](https://github.com/astral-sh/rye/issues/288 "GitHub Issue astral-sh/rye #288") * Calling `rye init` on the root directory no longer fails. [#274](https://github.com/astral-sh/rye/issues/274 "GitHub Issue astral-sh/rye #274") * `rye run`, `show`, `pin`, `shell` and `build` now take a `--pyproject` argument. [#232](https://github.com/astral-sh/rye/issues/232 "GitHub Issue astral-sh/rye #232") 0.5.0 ----- Released on 2023-05-31 * Rye will no longer enforce a downloaded interpreter for the internal toolchain. If one has been registered that is compatible it will be used. Additionally the installer now supports the `RYE_TOOLCHAIN` environment variable which allows a user to supply an already existing Python interpreter at install time. [#267](https://github.com/astral-sh/rye/issues/267 "GitHub Issue astral-sh/rye #267") * The `publish` command now supports `--yes` to disable prompts. [#270](https://github.com/astral-sh/rye/issues/270 "GitHub Issue astral-sh/rye #270") * When a Python debug build (`Py_DEBUG`) is registered as custom toolchain, `-dbg` is automatically appended to the name by default. [#269](https://github.com/astral-sh/rye/issues/269 "GitHub Issue astral-sh/rye #269") * lto+pgo builds are now preferred for the Python toolchain builds when available. [#268](https://github.com/astral-sh/rye/issues/268 "GitHub Issue astral-sh/rye #268") * It's now possible for `.python-version` to request partial Python versions in which case the latest available is used. In particular this means that a version like `3.10` can be written into `.python-version` rather than `3.10.11`. This can be accomplished by invoking `pin` with the new `--relaxed` flag. [#255](https://github.com/astral-sh/rye/issues/255 "GitHub Issue astral-sh/rye #255") * Workspaces will no longer discover `pyproject.toml` files in virtualenvs or `.git` folders. [#266](https://github.com/astral-sh/rye/issues/266 "GitHub Issue astral-sh/rye #266") * Adding or removing dependencies with `add` or `remove` now reformats the `dependencies` array in the `pyproject.toml` file to multi-line with trailing commas. This should result in significantly better diffing behavior out of the box. [#263](https://github.com/astral-sh/rye/issues/263 "GitHub Issue astral-sh/rye #263") * Default build-system and license can be specified in global config. [#244](https://github.com/astral-sh/rye/issues/244 "GitHub Issue astral-sh/rye #244") * Fixed an issue where the `init` command would not let you create `flit` based projects. [#254](https://github.com/astral-sh/rye/issues/254 "GitHub Issue astral-sh/rye #254") * Resolve an error ("No such file or directory") shown after updates on Linux machines. [#252](https://github.com/astral-sh/rye/issues/252 "GitHub Issue astral-sh/rye #252") * The built-in updater now validates checksums of updates when updates have SHA-256 hashes available. [#253](https://github.com/astral-sh/rye/issues/253 "GitHub Issue astral-sh/rye #253") * `init` now accepts `--no-pin` to not create a `.python-version` file. [#247](https://github.com/astral-sh/rye/issues/247 "GitHub Issue astral-sh/rye #247") 0.4.0 ----- Released on 2023-05-29 * Releases starting with `0.4.0` onwards are published with SHA256 checksum files for all release assets. These files are not yet validated by the installer or updater however. * The `install` command can now install tools from custom indexes. [#240](https://github.com/astral-sh/rye/issues/240 "GitHub Issue astral-sh/rye #240") * Virtualenvs on Unix are now created with a hack to pre-configure TCL and TKinter. [#233](https://github.com/astral-sh/rye/issues/233 "GitHub Issue astral-sh/rye #233") * Fix invalid version error when using rye init with custom toolchain. [#234](https://github.com/astral-sh/rye/issues/234 "GitHub Issue astral-sh/rye #234") * Failed tool installations now properly clean up. [#225](https://github.com/astral-sh/rye/issues/225 "GitHub Issue astral-sh/rye #225") * Correctly swap the rye executable on windows when performing an update to a git version via `self update`. 0.3.0 ----- Released on 2023-05-27 * Support retrieving username and repository-url from credentials if not provided for the `publish` command. [#217](https://github.com/astral-sh/rye/issues/217 "GitHub Issue astral-sh/rye #217") * The installer now validates the availability of shared libraries on Linux with `ldd` and emits an error with additional information if necessary shared libraries are missing. [#220](https://github.com/astral-sh/rye/issues/220 "GitHub Issue astral-sh/rye #220") * It's now possible to configure http and https proxies. [#215](https://github.com/astral-sh/rye/issues/215 "GitHub Issue astral-sh/rye #215") * If a package is not found because it only has matching pre-releases, a warning is now printed to tell the user to pass `--pre`. [#218](https://github.com/astral-sh/rye/issues/218 "GitHub Issue astral-sh/rye #218") * Add `--username` parameter for rye publish. [#211](https://github.com/astral-sh/rye/issues/211 "GitHub Issue astral-sh/rye #211") * The shims are now more resilient. Previously a `pyproject.toml` file caused in all cases a virtualenv to be created. Now this will only happen when the `rye.tool.managed` flag is set to `true`. The old behavior can be forced via the global config. [#212](https://github.com/astral-sh/rye/issues/212 "GitHub Issue astral-sh/rye #212") 0.2.0 ----- Released on 2023-05-23 * Resolved a bug where on Windows hitting the shift key (or some other keys) in confirm prompts would cause an error. * The installer on Windows now warns if symlinks are not enabled and directs the user to enable developer mode. The `--version` output now also shows if symlinks are available. [#205](https://github.com/astral-sh/rye/issues/205 "GitHub Issue astral-sh/rye #205") * Support auto fix requires-python when there is a conflict. [#160](https://github.com/astral-sh/rye/issues/160 "GitHub Issue astral-sh/rye #160") * Added support for custom indexes. [#199](https://github.com/astral-sh/rye/issues/199 "GitHub Issue astral-sh/rye #199") * `rye add` no longer complains when a local version information is in the version. [#199](https://github.com/astral-sh/rye/issues/199 "GitHub Issue astral-sh/rye #199") 0.1.2 ----- Released on 2023-05-22 * Fixed dev-dependencies not being installed when using workspace. [#170](https://github.com/astral-sh/rye/issues/170 "GitHub Issue astral-sh/rye #170") * `init` no longer creates invalid flit config. [#195](https://github.com/astral-sh/rye/issues/195 "GitHub Issue astral-sh/rye #195") * Support direct references when adding a package. [#158](https://github.com/astral-sh/rye/issues/158 "GitHub Issue astral-sh/rye #158") * Fixed a bug with uninstall on Unix platforms. [#197](https://github.com/astral-sh/rye/issues/197 "GitHub Issue astral-sh/rye #197") 0.1.1 ----- Released on 2023-05-18 * The installer on windows will now ask for a key to be pressed so it does not close the window without information. [#183](https://github.com/astral-sh/rye/issues/183 "GitHub Issue astral-sh/rye #183") * Fixed an issue on macOS where the installer would die with "os error 24" when directly piped to bash. [#184](https://github.com/astral-sh/rye/issues/184 "GitHub Issue astral-sh/rye #184") 0.1.0 ----- Released on 2023-05-17 * Rye now comes with binary releases for some platforms. * A new `self uninstall` command was added to uninstall rye and the new `self update` command updates to the latest release version. * Rye now includes a `publish` command for publishing Python packages to a package repository. [#86](https://github.com/astral-sh/rye/issues/86 "GitHub Issue astral-sh/rye #86") * Script declarations in `pyproject.toml` now permit chaining and custom environment variables. [#153](https://github.com/astral-sh/rye/issues/153 "GitHub Issue astral-sh/rye #153") * Added `tools install` and `tools uninstall` as aliases for `install` and `uninstall` and added `tools list` to show all installed tools. * Rye is now capable of downloading a selected set of PyPy releases. To do so use `rye pin [[email protected]](/cdn-cgi/l/email-protection) ` or any other supported PyPy release. * Custom cpython toolchains are now registered just as `cpython` rather than `custom-cpython`. * Rye now supports Python down to 3.7. * Rye's `self` command now includes a `completion` subcommand to generate a completion script for your shell. * The downloaded Python distributions are now validated against the SHA-256 hashes. * Rye now builds on windows. This is even more experimental though than support for Linux and macOS. * Added `--features` and `--all-features` for `lock` and `sync`. * Rye will now look at the `RYE_HOME` to determine the location of the `.rye` folder. If it's not set, `$HOME/.rye` is used as before. * Rye now has a most consistent handling for virtualenv versions. If `.python-version` is provided, that version is used. Otherwise if `requires-python` is set in the `pyproject.toml`, that version is used instead. When a new project is created the `.python-version` file is written and the current latest cpython version is picked. * It's now possible to explicitly set the `name` of the project when initializing a new one. * Rye's `init` command now attempts to initialize projects with `git` and will automatically create a `src/project_name/__init__.py` file. * Rye can now also generate a license text when initializing projects. * Rye now supports negative (exclusion) dependencies. These can be used to prevent a dependency from installing, even if something else in the graph depends on it. Use `rye add --exclude package-name` to add such a dependency. * `sync` now accepts `--no-lock` to prevent updating the lock file. * Rye's `add` command now accepts a `--pre` parameter to include pre-release. * Rye's `pin` command now updates the pyproject.toml requires-python. * Rye's `install` command now accepts a `--include-dep` parameter to include scripts from one or more given dependencies. * Rye now honors `requires-python` in the `add` command. This means the the initial resolution will not pick a version higher than what's supported by the lower boundary. * When installing packages as global tools, a warning is now emitted if there were no scripts in the package. Additionally installing packages from local paths and zip files is now supported. * A `rye self update` command was added to compile and install the latest version via cargo. * Added more convenient ways to install from git/urls by supplying a `--git` or `--url` parameter. This will behind the scenes format a PEP 508 requirement string. * Added a `shell` command which will spawn a shell with the virtualenv activated. * Added a `make-req` command to conveniently format out PEP 508 requirement strings from parts. * The internal virtualenv used to manage `pip-tools` and other libraries now automatically updates when necessary. * `rye toolchain register` can now be used to register a local python installation as toolchain with rye. * `rye build` was added to allow building `sdist` and `bdist_wheel` distributions. * Rye now correctly handles whitespace in folder names. Back to top --- # Configuration - Rye [](https://github.com/astral-sh/rye/edit/main/docs/guide/config.md "Edit this page") Configuration ============= Most of Rye's configuration is contained within the `pyproject.toml` file. There is however also a bit of global configuration to influence how it works. Changing Home Folder -------------------- By default Rye places all its configuration in `~/.rye` on Unix and `%USERPROFILE%\.rye` on Windows. This behavior can be changed via the `RYE_HOME` environment variable. This is useful if you do not like the default location where Rye places its configuration or if you need to isolate it. Home Folder Structure --------------------- The `.rye` home folder contains both user configuration as well as Rye-managed state such as [installed toolchains](../toolchains/) . The following files and folders are placed within the `.rye` folder. Note that not all are always there. ### `config.toml` This is a configuration file that influences how Rye operates. Today very little configuration is available there. For the available config keys see [Config File](#config-file) . ### `self` While Rye is written in Rust, it uses a lot of Python tools internally. These are maintained in an internal virtualenv stored in this location. ### `py` In this folder Rye stores the different [toolchains](../toolchains/) . Normally those are folders containing downloaded Python distributions, but they can also be symlinks or special reference files. ### `shims` This folder contains shim binaries. These binaries are for instance the `python` executable which automatically proxies to the current virtualenv or globally installed [tools](../tools/) . Config File ----------- The config file `config.toml` in the `.rye` folder today is only used to manage defaults. This is a fully annotated config file: ``[default] # This is the default value that is written into new pyproject.toml # files for the `project.requires-python` key requires-python = ">= 3.8" # This is the default toolchain that is used toolchain = "[[email protected]](/cdn-cgi/l/email-protection) " # This is the default build system that is used build-system = "hatchling" # This is the default license that is used license = "MIT" # This sets the default author (overrides the defaults from git). The # format here is "Name ". author = "Full Name <[[email protected]](/cdn-cgi/l/email-protection) >" # The dependency operator to use by default for dependencies. The options are # '>=', '~=', and '=='. The default currently is '>='. This affects the behavior # of `rye add`. dependency-operator = ">=" [proxy] # the proxy to use for HTTP (overridden by the http_proxy environment variable) http = "http://127.0.0.1:4000" # the proxy to use for HTTPS (overridden by the https_proxy environment variable) https = "http://127.0.0.1:4000" [behavior] # When set to `true` the `managed` flag is always assumed to be `true`. force-rye-managed = false # Enables global shims when set to `true`. This means that the installed # `python` shim will resolve to a Rye-managed toolchain even outside of # virtual environments. global-python = false # Enable or disable automatic `sync` after `add` and `remove`. This defaults # to `true` when uv is enabled and `false` otherwise. autosync = true # Marks the managed .venv in a way that cloud-based synchronization systems # like Dropbox and iCloud Files will not upload it. This defaults to `true` # as a .venv in cloud storage typically does not make sense. Set this to # `false` to disable this behavior. venv-mark-sync-ignore = true # When set to `true` Rye will fetch certain interpreters with build information. # This will increase the space requirements, will put the interpreter into an # extra folder called `./install/` and place build artifacts adjacent in `./build`. fetch-with-build-info = false # An array of tables with optional sources. Same format as in pyproject.toml [[sources]] name = "default" url = "https://pypi.org/simple/"`` Manipulating Config ------------------- new in **0.9.0** The configuration can be read and modified with `rye config`. The keys are in dotted notation. `--get` reads a key, `--set`, `--set-int`, `--set-bool`, and `--unset` modify one. `rye config --set proxy.http=http://127.0.0.1:4000 rye config --set-bool behavior.force-rye-managed=true rye config --get default.requires-python` For more information see [`config`](../commands/config/) . Per Project Config ------------------ For the project-specific `pyproject.toml` config see [pyproject.toml](../pyproject/) . Back to top --- # Python Project - Rye [](https://github.com/astral-sh/rye/edit/main/docs/guide/pyproject.md "Edit this page") Python Project (`pyproject.toml`) ================================= Rye tries to avoid a lot of proprietary configuration in the `pyproject.toml` file but a bit is necessary. Here are the most important keys that Rye expects: `project.dependencies` ---------------------- This key is used to manage dependencies. They work exactly like you expect from a regular `pyproject.toml` file and in fact Rye changes nothing about this. However Rye is capable of modifying these entries with the `rye add` and `rye remove` commands. `[project] dependencies = [ "mkdocs~=1.4.3", "mkdocs-material~=9.1.12", "pymdown-extensions~=9.11", ]` `project.scripts` ----------------- This key specifies the scripts that are to be generated and installed into the virtual environment during `sync`. These scripts will invoke the configured entry point. `[project.scripts] my-hello-script = 'hello:main'` This configuration will generate a script `my-hello-script` that will call the `main` function of the `hello` module. Scripts can be installed using [`rye sync`](../commands/sync/) and run using [`rye run`](../commands/run/) : `$ rye sync $ rye run my-hello-script Hello from hello!` `tool.rye.dev-dependencies` --------------------------- This works similar to `project.dependencies` but holds development only dependencies. These can be added here automatically via `rye add --dev`. `[tool.rye] dev-dependencies = ["black~=23.3.0"]` Dev dependencies are installed automatically unless `--no-dev` is passed to `sync`. `tool.rye.excluded-dependencies` -------------------------------- This is a special key that contains dependencies which are never installed, even if they are pulled in as indirect dependencies. These are added here automatically with `rye add --excluded`. `[tool.rye] excluded-dependencies = ["cffi"]` `tool.rye.universal` -------------------- new in **0.36.0** When this flag is enabled all `lock` and `sync` operations in the project or workspace operate as if `--universal` is passed. This means that the dependency resolver will attempt to generate a resolution that's valid on all platforms, operating systems, and architectures, rather than a resolution that's specific to the current platform. `[tool.rye] universal = true` `tool.rye.generate-hashes` -------------------------- new in **0.35.0** When this flag is enabled all `lock` and `sync` operations in the project or workspace operate as if `--generate-hashes` is passed. This means that all dependencies in all lock files will include a hash. `[tool.rye] generate-hashes = true` `tool.rye.lock-with-sources` ---------------------------- new in **0.18.0** When this flag is enabled all `lock` and `sync` operations in the project or workspace operate as if `--with-sources` is passed. This means that all lock files contain the full source references. Note that this can create lock files that contain credentials if the sources have credentials included in the URL. `[tool.rye] lock-with-sources = true` `tool.rye.managed` ------------------ new in **0.3.0** This key tells rye that this project is supposed to be managed by Rye. This key primarily affects some automatic creation of virtualenvs. For instance Rye will not try to initialize a virtualenv when using shims without this flag. It can be forced enabled in the global config. `[tool.rye] managed = true` `tool.rye.virtual` ------------------ new in **0.20.0** If this key is set to `true` the project is declared as a virtual project. This is a special mode in which the package itself is not installed, but only the dependencies are. This is for instance useful if you are not creating a Python project, but you are depending on Python software. As an example you can use this to install software written in Python. This key is set to true when `rye init` is invoked with the `--virtual` flag. `[tool.rye] virtual = true` For more information consult the [Virtual Project Guide](../virtual/) . `tool.rye.sources` ------------------ This is an array of tables with sources that should be used for locating dependencies. This lets you use indexes other than PyPI. These sources can also be configured in the main `config.toml` config file with the same syntax. `[[tool.rye.sources]] name = "default" url = "http://pypi.org/simple/"` For more information about configuring sources see [Dependency Sources](../sources/) . `tool.rye.scripts` ------------------ This key can be used to register custom scripts that are exposed via `rye run`. Each key is a script, and each value is the configuration for that script. Normally the value is an object with different keys with the most important key being `cmd` which holds the command to execute. However if only `cmd` is set, then the object is optional. `cmd` itself can either be set to a string or an array of arguments. `[tool.rye.scripts] # These three options are equivalent: devserver = "flask run --app ./hello.py --debug" devserver-alt = ["flask", "run", "--app", "./hello.py", "--debug"] devserver-explicit = { cmd = "flask run --app ./hello.py --debug" }` The following keys are possible for a script: ### `cmd` The command to execute. This is either a `string` or an `array` of arguments. In either case shell specific interpolation is unavailable. The command will invoke one of the tools in the virtualenv if it's available there. `[tool.rye.scripts] devserver = { cmd = "flask run --app ./hello.py --debug" } http = { cmd = ["python", "-mhttp.server", "8000"] }` ### `env` This key can be used to provide environment variables with a script: `[tool.rye.scripts] devserver = { cmd = "flask run --debug", env = { FLASK_APP = "./hello.py" } }` ### `env-file` new in **0.30.0** This is similar to `env` but rather than setting environment variables directly, it instead points to a file that should be loaded (relative to the `pyproject.toml`): `[tool.rye.scripts] devserver = { cmd = "flask run --debug", env-file = ".dev.env" }` ### `chain` This is a special key that can be set instead of `cmd` to make a command invoke multiple other commands. Each command will be executed one after another. If any of the commands fails, the rest of the commands won't be executed and the chain fails. `[tool.rye.scripts] lint = { chain = ["lint:black", "lint:flake8" ] } "lint:black" = "black --check src" "lint:flake8" = "flake8 src"` ### `call` This is a special key that can be set instead of `cmd` to make a command invoke python functions or modules. The format is one of the three following formats: * ``: equivalent to `python -m ` * `:`: runs `` from `` and exits with the return value * `:()`: passes specific arguments to the function Extra arguments provided on the command line are passed in `sys.argv`. `[tool.rye.scripts] serve = { call = "http.server" } help = { call = "builtins:help" } hello-world = { call = "builtins:print('Hello World!')" }` `tool.rye.workspace` -------------------- When a table with that key is stored, then a project is declared to be a [workspace](../workspaces/) root. By default all Python projects discovered in sub folders will then become members of this workspace and share a virtualenv. Optionally the `members` key (an array) can be used to restrict these members. In that list globs can be used. The root project itself is always a member. `[tool.rye.workspace] members = ["mylib-*"]` For more information consult the [Workspaces Guide](../workspaces/) . Back to top --- # Syncing and Locking - Rye [](https://github.com/astral-sh/rye/edit/main/docs/guide/sync.md "Edit this page") Syncing and Locking =================== Rye uses [`uv`](https://github.com/astral-sh/uv) to manage dependencies. In order to download dependencies rye creates two "lockfiles" (called `requirements.lock` and `requirements-dev.lock`). These are not real lockfiles, but they fulfill a similar purpose until a better solution has been implemented. Whenever `rye sync` is called, it will update lockfiles as well as the virtualenv. If you only want to update the lockfiles, then `rye lock` can be used. Lock ---- When locking, some options can be provided to change the locking behavior. These flags are also all available on `rye sync`. ### `--update` / `--update-all` Updates a specific or all requirements to the latest and greatest version. Without this flag a dependency will only be updated if necessary. `rye lock --update-all` ### `--features` / `--all-features` Python packages can have extra dependencies. By default the local package that is installed will only be installed with the default features. If for instance you have an extra dependency this will only be installed if the feature is enabled. `rye add --optional=web flask rye lock --features=web` When working with [workspaces](../workspaces/) , the package name needs to be prefixed with a slash: `rye lock --features=package-name/feature-name` The `--features` parameter can be passed multiple times and features can also be comma separated. To turn on all features, the `--all-features` parameter can be used. `rye lock --all-features` ### `--pre` By default updates and version resolution will not consider pre-releases of packages. If you do want to include those, pass `--pre` `rye lock Flask --pre` ### `--with-sources` new in **0.18.0** By default (unless the `tool.rye.lock-with-sources` config key is set to `true` in the `pyproject.toml`) lockfiles are not generated with source references. This means that if custom sources are used the lockfile cannot be installed via `uv` or `pip`, unless `--find-links` and other parameters are manually passed. This can be particularly useful when the lockfile is used for Docker image builds. When this flag is passed then the lockfile is generated with references to `--index-url`, `--extra-index-url` or `--find-links`. `rye lock --with-sources` Sync ---- Syncing takes the same parameters as `lock` and then some. Sync will usually first do what `lock` does and then use the lockfiles to update the virtualenv. ### `--no-lock` To prevent the lock step from automatically running, pass `--no-lock`. `rye sync --no-lock` ### `--no-dev` Only sync based on the production lockfile (`requirements.lock`) instead of the development lockfile (`requirements-dev.lock`). `rye sync --no-dev` Platform Compatibility ---------------------- By default, lockfiles depend on the platform they were generated on. For example, if your project relies on platform-specific packages and you generate lockfiles on Windows, these lockfiles will include Windows-specific projects. Consequently, they won't be compatible with other platforms like Linux or macOS. To generate a cross-platform lockfile, you can enable uv's `universal` setting by adding the following to your `pyproject.toml`: `[tool.rye] universal = true` Back to top --- # Shims - Rye [](https://github.com/astral-sh/rye/edit/main/docs/guide/shims.md "Edit this page") Shims ===== After installation Rye places two shims on your `PATH`: `python` and `python3`. These shims have specific behavior that changes depending on if they are used within a Rye managed project or outside. Inside a Rye managed project they resolve to the Python interpreter of the virtualenv. This means that even if you do not enable the virtualenv, you can just run `python` in a shell, and it will automatically operate in the right environment. Outside a Rye managed project it typically resolves to your system Python, though you can also opt to have it resolve to a Rye managed Python installation for you. This is done so that it's not disruptive to your existing workflows which might depend on the System python installation. Global Shims ------------ new in **0.9.0** To enable global shims, you need to enable the `global-python` flag in the [`config.toml`](../config/) file: `rye config --set-bool behavior.global-python=true` Afterwards if you run `python` outside of a Rye managed project it will spawn a Python interpreter that is shipped with Rye. It will honor the closest `.python-version` file for you. Additionally you can also explicitly request a specific Python version by adding `+VERSION` after the `python` command. For instance this runs a script with Python 3.8: `python +3.8 my-script.py` Note Selecting a specific Python version this way only works outside of Rye managed projects. Within Rye managed projects, the version needs to be explicitly selected via `.python-version` or with the `requires-python` key in `pyproject.toml`. Back to top --- # Building and Publishing - Rye [](https://github.com/astral-sh/rye/edit/main/docs/guide/publish.md "Edit this page") Building and Publishing ======================= Rye currently uses [build](https://github.com/pypa/build) to build the package and uses [twine](https://github.com/pypa/twine) to publish it. Build ----- By default, `rye` will build both the sdist and wheel targets in the `dist` directory. The command for this is called [`build`](../commands/build/) . `rye build` You can use the `--sdist` or `--wheel` flag to build the specific target, or specify the output directory with `--out`. `rye build --wheel --out target` If you want to clean the build directory before building, run: `rye build --clean` Publish ------- Rye will publish the distribution files under the `dist` directory to PyPI by default. `rye publish` You might be asked to input your access token and some other info if needed. `No access token found, generate one at: https://pypi.org/manage/account/token/ Access token:` You can also specify the distribution files to be published: `rye publish dist/example-0.1.0.tar.gz` ### \--repository Rye supports publishing the package to a different repository by using the `--repository` and `--repository-url` flags. For example, to publish to the test PyPI repository: `rye publish --repository testpypi --repository-url https://test.pypi.org/legacy/` ### \--yes You can optionally set the `--yes` flag to skip the confirmation prompt. This can be useful for CI/CD pipelines. `rye publish --token --yes` Rye will store your repository info in `$HOME/.rye/credentials` for future use. ### \--skip-existing You can use `--skip-existing` to skip any distribution files that have already been published to the repository. Note that some repositories may not support this feature. Back to top --- # Rust Modules - Rye [](https://github.com/astral-sh/rye/edit/main/docs/guide/rust.md "Edit this page") Rust Modules ============ Rye recommends using [maturin](https://github.com/PyO3/maturin) to develop Rust Python extension modules. This process is largely automated and new projects can be created with `rye init`. New Project ----------- `rye init my-project --build-system maturin cd my-project` The following structure will be created: `. ├── .git ├── .gitignore ├── .python-version ├── README.md ├── pyproject.toml ├── Cargo.toml ├── python └── my_project └── __init__.py └── src └── lib.rs` Iterating --------- When you use maturin as a build system then `rye sync` will automatically build the rust extension module into your venv. Likewise `rye build` will use maturin to trigger a wheel build. For faster iteration it's recommended to use `maturin` directly. If you want to use other maturin commands such as `maturin develop` you can install it as a global tool: `rye install maturin` Rye recommends mixed python/rust modules. In that case you can save some valuable iteration time by running `maturin develop --skip-install`: `maturin develop --skip-install` Back to top --- # Dependency Sources - Rye [](https://github.com/astral-sh/rye/edit/main/docs/guide/sources.md "Edit this page") Dependency Sources ================== new in **0.2.0** Normally Rye loads packages from PyPI only. However it is possible to instruct it to load packages from other indexes as well. Adding a Source --------------- An index can be added to a project or workspace (via `pyproject.toml`) or into the [global config](../config/#config-file) . Rye will always consult both files where the `pyproject.toml` file wins over the global config. Each source needs to have a unique name. The default source is always called `default` and out of the box points to PyPI. Global SourceProject Source Add this to `~/.rye/config.toml`: `[[sources]] name = "company-internal" url = "https://company.internal/simple/"` Add this to `pyproject.toml`: `[[tool.rye.sources]] name = "company-internal" url = "https://company.internal/simple/"` changed in **0.4.0** Sources in the global config are also considered for tool installations. ### Index Types Rye supports different types of sources and also allows overriding the `default` PyPI index. If you give another source the name `default`, PyPI will no longer be used for resolution. Regular IndexFind LinksDefault Index `[[sources]] name = "company-internal" url = "https://company.internal/simple/" type = "index" # this is implied` `[[sources]] name = "company-internal" url = "https://company.internal/" type = "find-links"` `[[sources]] name = "default" url = "https://company.internal/simple/"` Warning Please take note that the default index cannot be of type `find-links`. Source Types ------------ The two sources types (`index` vs `find-links`) are determined by the underlying pip infrastructure: ### `index` This is a [PEP 503](https://www.python.org/dev/peps/pep-0503/) type index as provided by tools such as PyPI or [devpi](https://github.com/devpi/devpi) . It corresponds to the arguments `--index-url` or `--extra-index-url` in pip. Note: see the [`uv` documentation](https://github.com/astral-sh/uv/blob/main/PIP_COMPATIBILITY.md#packages-that-exist-on-multiple-indexes) for more on the use of multiple indexes. ### `find-links` This is a source that can be of a variety of types and has to point to a file path or hosted HTML page linking to packages. It corresponds to the `--find-links` argument. The format of the HTML page is somewhat underspecified but generally all HTML links pointing to `.tar.gz` or `.whl` files are considered. Index Authentication -------------------- HTTP basic auth is supported for index authentication. It can be supplied in two ways. `username` and `password` can be directly embedded in the config, or they can be supplied with environment variables. Configured CredentialsEnvironment Variables `[[sources]] name = "company-internal" url = "https://company.internal/simple/" username = "username" password = "super secret"` `[[sources]] name = "company-internal" url = "https://${INDEX_USERNAME}:${INDEX_PASSWORD}@company.internal/simple/"` SSL/TLS Verification -------------------- By default a source needs to be SSL/TLS protected. If not, rye will refuse to honor the source. You can override this by setting `verify-ssl` to `false`: `[[sources]] name = "company-internal" url = "http://company.internal/simple/" verify-ssl = false` Back to top --- # Dependencies - Rye [](https://github.com/astral-sh/rye/edit/main/docs/guide/deps.md "Edit this page") Dependencies ============ Dependencies are declared in [pyproject.toml](../pyproject/) however adding them can be simplified with the [`rye add`](../commands/add/) command. In the most simple invocation it adds a regular dependency, but it can be customized. Adding Basic Dependency ----------------------- To add a regular dependency just invoke [`rye add`](../commands/add/) with the name of the Python package: `rye add Flask` If you also want to define a version, use a [PEP 508](https://peps.python.org/pep-0508/) requirement: `rye add "Flask>=2.0"` For extra/feature dependencies you can either use PEP 508 syntax or use `--features`: `rye add "Flask[dotenv]" rye add Flask --features=dotenv` These dependencies are stored in [`project.dependencies`](../pyproject/#projectdependencies) . Note about pre-releases By default `add` will not consider pre-releases. This means if you add a dependency that has `.dev` or similar in the version number you will not find a match. To consider them, add them with `--pre`: `rye add "Flask==2.0.0rc2" --pre` Development Dependencies ------------------------ For dependencies that should only be installed during development pass `--dev` `rye add --dev black` These dependencies are stored in the non-standard [`tool.rye.dev-dependencies`](../pyproject/#toolryedev-dependencies) key. To run tools added this way without enabling the virtualenv use [`rye run`](../commands/run/) : `rye run black` Git / Local Dependencies ------------------------ To add a local or git dependency, you can pass additional parameters like `--path` or `--git`: `rye add Flask --git=https://github.com/pallets/flask rye add My-Utility --path ./my-utility` Note that when adding such dependencies, it's necessary to also provide the name of the package. Additionally for git dependencies all kinds of extra parameters such as `--tag`, `--rev` or `--branch` are supported. When working with local dependencies it's strongly encouraged to configure a [workspace](../pyproject/#toolryeworkspace) . Back to top --- # Virtual Projects - Rye [](https://github.com/astral-sh/rye/edit/main/docs/guide/virtual.md "Edit this page") Virtual Projects ================ new in **0.20.0** Virtual projects are projects which are themselves not installable Python packages, but that will sync their dependencies. They are declared like a normal python package in a `pyproject.toml`, but they do not create a package. Instead the `tool.rye.virtual` key is set to `true`. For instance this is useful if you want to use a program like `mkdocs` without declaring a package yourself: `rye init --virtual rye add mkdocs rye sync rye run mkdocs` This will create a `pyproject.toml` but does not actually declare any python code itself. Yet when syncing you will end up with mkdocs in your project. Behavior Changes ---------------- When syncing the project itself is never installed into the virtualenv as it's not considered to be a valid package. Likewise you cannot publish virtual packages to PyPI or another index. Limitations ----------- Virtual projects can not have optional dependencies. These even if declared are not installed. Workspaces ---------- If a [workspace](../workspaces/) does not have a toplevel package it's recommended that it's declared as virtual. Back to top --- # Workspaces - Rye [](https://github.com/astral-sh/rye/edit/main/docs/guide/workspaces.md "Edit this page") Workspaces ========== Workspaces are a feature that allows you to work with multiple packages that have dependencies on each other. A workspace is declared by setting the `tool.rye.workspace` key in `pyproject.toml`. Afterwards, all projects within that workspace share a singular virtualenv. Declaring Workspaces -------------------- A workspace is declared in the "toplevel" `pyproject.toml`. At the very least the key `tool.rye.workspace` needs to be added. It's also recommended to set a glob pattern in the `members` key to prevent accidentally including unintended folders as projects. `[tool.rye.workspace] members = ["myname-*"]` This declares a workspace where all folders starting with the name `myname-` are considered. If the toplevel workspace itself should not be a project, then it should be declared as a virtual package: `[tool.rye] virtual = true [tool.rye.workspace] members = ["myname-*"]` For more information on that, see [Virtual Packages](../virtual/) . Syncing ------- In a workspace, it does not matter which project you are working with, the entire workspace is synchronized at all times. This has some atypical consequences but simplifies the general development workflow. When a package depends on another package it's first located in the workspace locally before it's attempted to be downloaded from an index. The `--all-features` flag is automatically applied to all packages, but to turn on the feature of a specific package the feature name must be prefixed. For instance to enable the `foo` extra feature of the `myname-bar` package you would need to do this: `rye sync --features=myname-bar/foo` Back to top --- # Docker - Rye [](https://github.com/astral-sh/rye/edit/main/docs/guide/docker.md "Edit this page") Building a Container with Docker ================================ If you want to put your Python code into a container, you probably have some server code that you don't submit to PyPI or another registry. If that's the case, read on. Else, skip to [the next section](#container-from-a-python-package) . This guide requires some familiarity with Docker and Dockerfiles. Container from Source --------------------- 1. Make sure that your project is set up as a [virtual project](../virtual/) . This means that you can't install it, and it won't mark itself as a dependency. If you need your project to be installable, go to [the next section](#container-from-a-python-package) . * Your `pyproject.toml` should contain `virtual = true` under the `[tool.rye]` section. If it's not there, add it and run `rye sync`. * If you're just setting up a project, run `rye init --virtual` instead of `rye init`. 2. Create a `Dockerfile` in your project root with the following content, using [`uv`](https://github.com/astral-sh/uv) : `FROM python:slim RUN pip install uv WORKDIR /app COPY requirements.lock ./ RUN uv pip install --no-cache --system -r requirements.lock COPY src . CMD python main.py` Or, using `pip`: `FROM python:slim WORKDIR /app COPY requirements.lock ./ RUN PYTHONDONTWRITEBYTECODE=1 pip install --no-cache-dir -r requirements.lock COPY src . CMD python main.py` 3. You can now build your image like this: `docker build .` ### Dockerfile Adjustments The `Dockerfile`s in this guide are examples. Some adjustments you might want to make: * The command (`CMD python src/main.py`) should point to your script. * Adjust the base image (`FROM python:slim`): * Prefer a tagged version that matches the one from your `.python-version` file, e.g. `FROM python:3.12.0-slim`. * The `-slim` variants are generally a good tradeoff between image size and compatibility and should work fine for most workloads. But you can also use `-alpine` for smaller images (but potential compatibility issues) or no suffix for ones that contain more system tools. * If you need additional system packages, install them before copying your source code, i.e. before the line `COPY src .`. When using Debian-based images (i.e. `-slim` or no-suffix variants), that could look like this: `RUN apt-get update \ && apt-get install -y --no-install-recommends some-dependency another-dependency \ && rm -rf /var/lib/apt/lists/*` Container from a Python Package ------------------------------- If your code is an installable package, it's recommended that you first build it, then install it inside your Docker image. This way you can be sure that the image is exactly the same as what a user installation would be. An example `Dockerfile` might look like this with [`uv`](https://github.com/astral-sh/uv) : `FROM python:slim RUN pip install uv RUN --mount=source=dist,target=/dist uv pip install --no-cache /dist/*.whl CMD python -m my_package` To build your docker image, you'll have to first build your wheel, like this: `rye build --wheel --clean docker build . --tag your-image-name` Note that this approach bundles your dependencies and code in a single layer. This might be nice for performance, but it also means that all dependencies are re-installed during every image build, and different versions won't share the disk space for the dependencies. The [Dockerfile adjustments from the previous section](#dockerfile-adjustments) apply. Explanations ------------ Rye's lockfile standard is the `requirements.txt` format from `pip` (and used by [`uv`](https://github.com/astral-sh/uv) ), so you don't actually need `rye` in your container to be able to install dependencies. This makes the Dockerfile much simpler and avoids the necessity for multi-stage builds if small images are desired. The `--no-cache-dir` and `--no-cache` parameters, passed to `pip` and `uv` respectively, make the image smaller by not writing any temporary files. While caching can speed up subsequent builds, it's not necessary in a container where the image is built once and then used many times. Similarly, the `PYTHONDONTWRITEBYTECODE=1` environment variable is set to avoid writing `.pyc` files, which are not needed in a container. (`uv` skips writing `.pyc` files by default.) Back to top --- # add - Rye [](https://github.com/astral-sh/rye/edit/main/docs/guide/commands/add.md "Edit this page") `add` ===== Adds a Python package to this project. The command takes a PEP 508 requirement string but provides additional helper arguments to make this process more user friendly. For instance instead of passing git references within the requirement string, the `--git` parameter can be used. If auto sync is disabled, after a dependency is added it's not automatically installed. To do that, you need to invoke the [`sync`](../sync/) command or pass `--sync`. To remove a dependency again use the [`remove`](../remove/) command. new in **0.26.0** Added support for auto-sync and the `--sync` / `--no-sync` flags. Example ------- Add the latest version of a dependency that is compatible with the configured Python version: `$ rye add flask Added flask>=3.0.1 as regular dependency` Add a dependency but add an optional extra feature: `$ rye add flask --features dotenv Added flask[dotenv]>=3.0.1 as regular dependency` Add a git dependency: `$ rye add flask --git https://github.com/pallets/flask Added flask @ git+https://github.com/pallets/flask as regular dependency` Add a local dependency: `$ rye add packagename --path path/to/packagename Added packagename @ file:///path/to/packagename as regular dependency` Arguments --------- * `...`: The package to add as PEP 508 requirement string. e.g. 'flask==2.2.3' Options ------- * `--git `: Install the given package from this git repository * `--url `: Install the given package from this URL * `--path `: Install the given package from this local path * `--absolute`: Force non interpolated absolute paths * `--tag `: Install a specific tag * `--rev `: Update to a specific git rev * `--branch `: Update to a specific git branch * `--features `: Adds a dependency with a specific feature * `--dev`: Add this as dev dependency * `--excluded`: Add this as an excluded dependency that will not be installed even if it's a sub dependency * `--optional `: Add this to an optional dependency group * `--pre`: Include pre-releases when finding a package version * `--pin `: Overrides the pin operator \[possible values: `equal`, `tilde-equal`, `greater-than-equal`\] * `--sync`: Runs `sync` automatically even if auto-sync is disabled. * `--no-sync`: Does not run `sync` automatically even if auto-sync is enabled. * `-v, --verbose`: Enables verbose diagnostics * `-q, --quiet`: Turns off all output * `-h, --help`: Print help (see a summary with `-h`) Back to top --- # Overview - Rye [](https://github.com/astral-sh/rye/edit/main/docs/guide/commands/index.md "Edit this page") Commands ======== This is a list of all the commands that rye provides: * [add](add/) : Adds a Python package to this project * [build](build/) : Builds a package for distribution * [config](config/) : Reads or updates the Rye configuration * [fetch](fetch/) : Fetches a Python interpreter for the local machine (alias) * [fmt](fmt/) : Run the code formatter on the project * [init](init/) : Initializes a new project * [install](install/) : Installs a global tool (alias) * [lock](lock/) : Updates the lockfiles without installing dependencies * [lint](lint/) : Run the linter on the project * [make-req](make-req/) : Builds and prints a PEP 508 requirement string from parts * [pin](pin/) : Pins a Python version to the project * [publish](publish/) : Publish packages to a package repository * [remove](remove/) : Remove a dependency from this project * [run](run/) : Runs a command installed into this package * [show](show/) : Prints the current state of the project * [sync](sync/) : Updates the virtualenv based on the pyproject.toml * [test](test/) : Runs the project's tests * [toolchain](toolchain/) : Helper utility to manage Python toolchains * [tools](tools/) : Helper utility to manage global tools. * [self](self/) : Rye self management * [uninstall](uninstall/) : Uninstalls a global tool (alias) * [version](version/) : Get or set project version Options ------- The toplevel `rye` command accepts the following options: * `--env-file` ``: This can be supplied multiple times to make rye load a given `.env` file. Note that this file is not referenced to handle the `RYE_HOME` variable which must be supplied as environment variable always. Back to top --- # build - Rye [](https://github.com/astral-sh/rye/edit/main/docs/guide/commands/build.md "Edit this page") `build` ======= Builds a package for distribution. Under normal circumstances Rye automatically builds packages for local development. However if you want to publish packages you need to first build them into source distributions (`sdist`) and binary/portable distributions (`wheel`). For more information see [Building and Publishing](../../publish/) . Example ------- This builds wheels and source distributions at once: `$ rye build building my-project * Creating virtualenv isolated environment... * Installing packages in isolated environment... (hatchling) * Getting build dependencies for sdist... * Building sdist... * Building wheel from sdist * Creating virtualenv isolated environment... * Installing packages in isolated environment... (hatchling) * Getting build dependencies for wheel... * Building wheel... Successfully built my_project-0.1.0.tar.gz and my_project-0.1.0-py3-none-any.whl` By default you will find the artifacts in the `dist` folder. Arguments --------- _no arguments_ Options ------- * `--sdist`: Build an sdist * `--wheel`: Build a wheel * `-a, --all`: Build all packages * `-p, --package `: Build a specific package * `-o, --out `: An output directory (defaults to `workspace/dist`) * `--pyproject `: Use this `pyproject.toml` file * `-c, --clean`: Clean the output directory first * `-v, --verbose`: Enables verbose diagnostics * `-q, --quiet`: Turns off all output * `-h, --help`: Print help Back to top --- # config - Rye [](https://github.com/astral-sh/rye/edit/main/docs/guide/commands/config.md "Edit this page") `config` ======== Reads or modifies the global `config.toml` file. The config file can be read via `--get` and it can be set with one of the set options (`--set`, `--set-int`, `--set-bool`, or `--unset`). Each of the set operations takes a key=value pair. All of these can be supplied multiple times. Example ------- This command turns on global shims: `rye config --set-bool behavior.global-python=true` Reads the currently set config value for global Python shims: `$ rye config --get behavior.global-python true` Show the path to the config: `$ rye config --show-path /Users/username/.rye/config.toml` Arguments --------- _no arguments_ Options ------- * `--get `: Reads a config key * `--set `: Sets a config key to a string * `--set-int `: Sets a config key to an integer * `--set-bool `: Sets a config key to a bool * `--unset `: Remove a config key * `--show-path`: Print the path to the config * `--format `: Request parseable output format rather than lines \[possible values: json\] * `-h, --help`: Print help (see a summary with '-h') Back to top --- # install - Rye [](https://github.com/astral-sh/rye/edit/main/docs/guide/commands/install.md "Edit this page") `install` ========= Installs a package as global tool. This command has two names to `rye tools install` and `rye install`. This can be used to install useful Python scripts globally into it's own separated virtualenv. For instance if you want to use the `black` formatter you can install it once. Normally only scripts installed by the top level dependency are installed. In some cases you might also want to install commands from sub-dependencies. In that case pass those dependencies with `--include-dep`. For more information see [Tools](/guide/tools/) . Example ------- `$ rye tools install pycowsay Looking in indexes: https://pypi.org/simple/ Collecting pycowsay Downloading pycowsay-0.0.0.2-py3-none-any.whl.metadata (965 bytes) Downloading pycowsay-0.0.0.2-py3-none-any.whl (4.0 kB) Installing collected packages: pycowsay Successfully installed pycowsay-0.0.0.2 Installed scripts: - pycowsay $ pycowsay "Great Stuff" ----------- < Great Stuff > ----------- \ ^__^ \ (oo)\_______ (__)\ )\/\ ||----w | || ||` Arguments --------- * `...`: The package to install as PEP 508 requirement string. Options ------- * `--git `: Install the given package from this git repository * `--url `: Install the given package from this URL * `--path `: Install the given package from this local path * `--absolute`: Force non interpolated absolute paths * `--tag `: Install a specific tag * `--rev `: Update to a specific git rev * `--branch `: Update to a specific git branch * `--features `: Adds a dependency with a specific feature * `--include-dep `: Include scripts from a given dependency * `--extra-requirement `: Additional dependencies to install that are not declared by the main package * `-p, --python `: Optionally the Python version to use * `-f, --force`: Force install the package even if it's already there * `-v, --verbose`: Enables verbose diagnostics * `-q, --quiet`: Turns off all output * `-h, --help`: Print help (see a summary with '-h') Back to top --- # fmt - Rye [](https://github.com/astral-sh/rye/edit/main/docs/guide/commands/fmt.md "Edit this page") `fmt` ===== new in **0.20.0** Run the code formatter on the project. This command is aliased to `format`. For more information about how to configure Ruff, have a look at the [Ruff Configuration Documentation](https://docs.astral.sh/ruff/configuration/) . Example ------- To format the code and write back to the files: `$ rye fmt 1 file reformatted, 231 files left unchanged` To just check if the code needs formatting: `$ rye fmt --check Would reformat: src/my_project/utils.py 1 file would be reformatted, 231 files already formatted` To pass extra arguments to the underlying `ruff` formatter use `--`: `$ rye fmt -- --diff --- src/my_project/utils.py +++ src/my_project/utils.py @@ -2,5 +2,4 @@ def foo(): - pass 1 file would be reformatted, 231 files already formatted` Format a specific file: `rye fmt src/foo.py` Arguments --------- * `[PATHS]...` List of files or directories to lint. If not supplied all files are formatted. * `[EXTRA_ARGS]...` Extra arguments to the formatter. These arguments are forwarded directly to the underlying formatter (currently always `ruff`). Note that extra arguments must be separated from other arguments with the `--` marker. Options ------- * `-a, --all`: Format all packages in the workspace * `-p, --package `: Format a specific package * `--pyproject `: Use this `pyproject.toml` file * `--check`: Run format in check mode * `-v, --verbose`: Enables verbose diagnostics * `-q, --quiet`: Turns off all output * `-h, --help`: Print help (see a summary with '-h') Back to top --- # init - Rye [](https://github.com/astral-sh/rye/edit/main/docs/guide/commands/init.md "Edit this page") `init` ====== This command initializes a new or existing Python project with Rye. Running it in a folder with an already existing Python project will attempt to convert it over and bootstrap Rye right there. Otherwise it can be used to create a completely new project from scratch. For more information see the [Basics Guide](../../basics/) . Example ------- ``$ rye init success: Initialized project in /Users/john/Development/my-project. Run `rye sync` to get started`` Arguments --------- * `[PATH]`: Where to place the project (defaults to current path) Options ------- * `--min-py `: Minimal Python version supported by this project * `-p, --py `: Python version to use for the virtualenv * `--no-readme`: Do not create a readme * `--no-pin`: Do not create .python-version file (requires-python will be used) * `--build-system `: Which build system should be used(defaults to hatchling)? \[possible values: `hatchling`, `setuptools`, `flit`, `pdm`, `maturin`\] * `--license `: Which license should be used? [SPDX identifier](https://spdx.org/licenses/) * `--name `: The name of the package * `--private`: Set "Private :: Do Not Upload" classifier, used for private projects * `--no-import`: Don't import from setup.cfg, setup.py, or requirements files * `--virtual`: Initialize this as a virtual package. A virtual package can have dependencies but is itself not installed as a Python package. It also cannot be published. * `-r, --requirements `: Requirements files to initialize pyproject.toml with * `--dev-requirements `: Development requirements files to initialize pyproject.toml with * `-v, --verbose`: Enables verbose diagnostics * `-q, --quiet`: Turns off all output * `-h, --help`: Print help (see a summary with '-h') Back to top --- # make-req - Rye [](https://github.com/astral-sh/rye/edit/main/docs/guide/commands/make-req.md "Edit this page") `make-req` ========== Builds and prints a PEP 508 requirement string from parts. This is a utility command that rarely needs to be used but can help creating requirements strings for pasting into other tools. It takes the same arguments as [`add`](../add/) but rather than adding the requirements into the requirements file it just spits out a formatted PEP 508 requirement string on stdout. Example ------- `$ rye make-req flask --git https://github.com/pallets/flask --rev 4df377cfbf flask @ git+https://github.com/pallets/flask@4df377cfbf` Arguments --------- * `[REQUIREMENTS]...` The package to add as PEP 508 requirement string. e.g. `'flask==2.2.3'` Options ------- * `--git `: Install the given package from this git repository * `--url `: Install the given package from this URL * `--path `: Install the given package from this local path * `--absolute`: Force non interpolated absolute paths * `--tag `: Install a specific tag * `--rev `: Update to a specific git rev * `--branch `: Update to a specific git branch * `--features `: Adds a dependency with a specific feature * `-h, --help`: Print help (see a summary with '-h') Back to top --- # lock - Rye [](https://github.com/astral-sh/rye/edit/main/docs/guide/commands/lock.md "Edit this page") `lock` ====== Updates the lockfiles without installing dependencies. Usually one would use the [`sync`](../sync/) command instead which both locks and installs dependencies. For more information see [Syncing and Locking](../../sync/) . Example ------- `$ rye lock Generating production lockfile: /Users/username/my-project/requirements.lock Generating dev lockfile: /Users/username/my-project/requirements-dev.lock Done!` Arguments --------- _no arguments_ Options ------- * `--update `: Update a specific package * `--update-all`: Update all packages to the latest * `--pre`: Update to pre-release versions * `--features `: Extras/features to enable when locking the workspace * `--all-features`: Enables all features * `--generate-hashes`: Set to true to lock with hashes in the lockfile * `--with-sources`: Set to true to lock with sources in the lockfile * `--pyproject `: Use this pyproject.toml file * `-v, --verbose`: Enables verbose diagnostics * `-q, --quiet`: Turns off all output * `-h, --help`: Print help (see a summary with '-h') Back to top --- # lint - Rye [](https://github.com/astral-sh/rye/edit/main/docs/guide/commands/lint.md "Edit this page") `lint` ====== new in **0.20.0** Run the linter on the project. This command is aliased to `check`. At the moment this always runs `ruff` in lint mode. For more information about how to configure Ruff, have a look at the [Ruff Configuration Documentation](https://docs.astral.sh/ruff/configuration/) . Example ------- Run the linter: ``$ rye lint src/myproject/sdk.py:1:8: F401 [*] `sys` imported but unused Found 1 error. [*] 1 fixable with the `--fix` option.`` For issues that can be auto fixed pass `--fix`: `$ rye lint --fix Found 1 error (1 fixed, 0 remaining).` To pass extra arguments: `$ rye lint -- --watch` Lint a specific file: `rye lint src/foo.py` Arguments --------- * `[PATHS]...` List of files or directories to lint. If not supplied all files are linted. * `[EXTRA_ARGS]...` Extra arguments to the linter. These arguments are forwarded directly to the underlying linter (currently always `ruff`). Note that extra arguments must be separated from other arguments with the `--` marker. Options ------- * `-a, --all`: Lint all packages in the workspace * `-p, --package `: Format a specific package * `--pyproject `: Use this `pyproject.toml` file * `--fix`: Automatically fix fixable issues * `-v, --verbose`: Enables verbose diagnostics * `-q, --quiet`: Turns off all output * `-h, --help`: Print help (see a summary with '-h') Back to top --- # pin - Rye [](https://github.com/astral-sh/rye/edit/main/docs/guide/commands/pin.md "Edit this page") `pin` ===== Pins a Python version to this project. This will update the `.python-version` to point to the provided version. Additionally it will update `requires-python` in the `pyproject.toml` if it's lower than the current version. This can be disabled by passing `--no-update-requires-python`. Which toolchain Rye prefers depends on the Rye version. From 0.22 onwards the latest compatible installed toolchain is picked, and only if a non existing one is found a download will be attempted. For older versions Rye will always attempt to download the latest available if it's not installed yet unless a precise pin is selected. Example ------- Pin a specific version of Python: `$ rye pin 3.9 pinned 3.9.18 in /Users/username/my-project` To issue a relaxed and not a specific pin use `--relaxed`: `$ rye pin 3.9 --relaxed pinned 3.9 in /Users/username/my-project` Arguments --------- * ``: The version of Python to pin This can be a short version (3.9) or a full one (`[[email protected]](/cdn-cgi/l/email-protection) `). Options ------- * `--relaxed`: Issue a relaxed pin * `--no-update-requires-python`: Prevent updating requires-python in the `pyproject.toml` * `--pyproject `: Use this `pyproject.toml` file * `-h, --help`: Print help (see a summary with '-h') Back to top --- # publish - Rye [](https://github.com/astral-sh/rye/edit/main/docs/guide/commands/publish.md "Edit this page") `publish` ========= Publish packages to a package repository. This publishes the packages which are produced by the build command. For more information see [Building and Publishing](../../publish/) . Example ------- Build and publish: `$ rye build $ rye publish` Publish a specific artifact: `$ rye publish dist/example-0.1.0.tar.gz` Arguments --------- * `[DIST]...`: The distribution files to upload to the repository (defaults to `/dist/*`) Options ------- * `-r, --repository `: The repository to publish to \[default: `pypi`\] * `--repository-url `: The repository url to publish to * `-u, --username `: The username to authenticate to the repository with * `--token `: An access token used for the upload * `--sign`: Sign files to upload using GPG * `-i, --identity `: GPG identity used to sign files * `--cert `: Path to alternate CA bundle * `--skip-existing`: Skip files already published (repository must support this feature) * `-y, --yes`: Skip prompts * `-v, --verbose`: Enables verbose diagnostics * `-q, --quiet`: Turns off all output * `-h, --help`: Print help (see a summary with '-h') Back to top --- # remove - Rye [](https://github.com/astral-sh/rye/edit/main/docs/guide/commands/remove.md "Edit this page") `remove` ======== Removes a package from this project. This removes a package from the `pyproject.toml` dependency list. If auto sync is disabled, after a dependency is removed it's not automatically uninstalled. To do that, you need to invoke the [`sync`](../sync/) command or pass `--sync`. new in **0.26.0** Added support for auto-sync and the `--sync` / `--no-sync` flags. Example ------- `$ rye remove flask Removed flask>=3.0.1` Arguments --------- * `...`: The packages to remove from the project Options ------- * `--dev`: Remove this from dev dependencies * `--optional `: Remove this from the optional dependency group * `--sync`: Runs `sync` automatically even if auto-sync is disabled. * `--no-sync`: Does not run `sync` automatically even if auto-sync is enabled. * `-v, --verbose`: Enables verbose diagnostics * `-q, --quiet`: Turns off all output * `-h, --help`: Print help (see a summary with '-h') Back to top --- # show - Rye [](https://github.com/astral-sh/rye/edit/main/docs/guide/commands/show.md "Edit this page") `show` ====== Prints the current state of the project. This can print out information about the virtualenv, the project or workspace as well as a list of installed dependencies. Example ------- Print out the status of a project: `$ rye show project: my-project path: /Users/username/my-project venv: /Users/username/my-project/.venv target python: 3.8 venv python: [[email protected]](/cdn-cgi/l/email-protection) virtual: false` Arguments --------- _no arguments_ Options ------- * `--installed-deps`: Print the currently installed dependencies. This option is being replaced with [`rye list`](../list/) * `--pyproject`: Use this `pyproject.toml` file * `-h, --help`: Print help (see a summary with '-h') Back to top --- # run - Rye [](https://github.com/astral-sh/rye/edit/main/docs/guide/commands/run.md "Edit this page") `run` ===== Runs a command installed into this package. This either runs a script or application made available in the virtualenv or a Rye specific script. For more information see [`rye.tool.scripts`](../../pyproject/#toolryescripts) . Example ------- Run a tool from the virtualenv: `$ rye run flask` Invoke it without arguments to see all available scripts: `$ rye run flask hello python python3 python3.9` Arguments --------- * `[COMMAND]`: The name of the command and the arguments to it. Options ------- * `-l, --list`: List all commands (implied without arguments) * `--pyproject`: Use this `pyproject.toml` file * `-h, --help`: Print help (see a summary with '-h') Back to top --- # sync - Rye [](https://github.com/astral-sh/rye/edit/main/docs/guide/commands/sync.md "Edit this page") `sync` ====== Updates the lockfiles and installs the dependencies into the virtualenv. For more information see [Syncing and Locking](../../sync/) . Example ------- Sync the project: `$ rye sync Reusing already existing virtualenv Generating production lockfile: /Users/username/my-project/requirements.lock Generating dev lockfile: /Users/username/my-project/requirements-dev.lock Installing dependencies ...` To sync without updating the lock file use `--no-lock`: `$ rye sync --no-lock` If you do not want dev dependencies to be installed use `--no-dev`: `$ rye sync --no-dev` To exit the sub shell run `exit`. Arguments --------- _no arguments_ Options ------- * `-f, --force`: Force the virtualenv to be re-created * `--no-dev`: Do not install dev dependencies * `--no-lock`: Do not update the lockfile. * `--update `: Update a specific package * `--update-all`: Update all packages to the latest * `--pre`: Update to pre-release versions * `--features `: Extras/features to enable when locking the workspace * `--all-features`: Enables all features * `--generate-hashes`: Set to true to lock with hashes in the lockfile * `--with-sources`: Set to true to lock with sources in the lockfile * `--pyproject `: Use this pyproject.toml file * `-v, --verbose`: Enables verbose diagnostics * `-q, --quiet`: Turns off all output * `-h, --help`: Print help (see a summary with '-h') Back to top --- # test - Rye [](https://github.com/astral-sh/rye/edit/main/docs/guide/commands/test.md "Edit this page") `test` ====== new in **0.28.0** Run the test suites of the project. At the moment this always runs `pytest`. Note that `pytest` must be installed into the virtual env unlike `ruff` which is used behind the scenes automatically for linting and formatting. Thus in order to use this, you need to declare `pytest` as dev dependency. `$ rye add --dev pytest` It's recommended to place tests in a folder called `tests` adjacent to the `src` folder of your project. For more information about how to use pytest, have a look at the [Pytest Documentation](https://docs.pytest.org/en/8.0.x/) . Example ------- Run the test suite: `$ rye test platform win32 -- Python 3.11.1, pytest-8.0.2, pluggy-1.4.0 rootdir: /Users/john/Development/stuff plugins: anyio-4.3.0 collected 1 item stuff/tests/test_batch.py . [100%]` Arguments --------- * `[EXTRA_ARGS]...` Extra arguments to the test runner. These arguments are forwarded directly to the underlying test runner (currently always `pytest`). Note that extra arguments must be separated from other arguments with the `--` marker. Options ------- * `-a, --all`: Test all packages in the workspace * `-p, --package `: Run the test suite of a specific package * `--pyproject `: Use this `pyproject.toml` file * `-v, --verbose`: Enables verbose diagnostics * `-q, --quiet`: Turns off all output * `-i, --ignore`: Ignore the specified directory * `-s`, `--no-capture`: Disable stdout/stderr capture for the test runner * `-h, --help`: Print help (see a summary with '-h') Back to top --- # Overview - Rye [](https://github.com/astral-sh/rye/edit/main/docs/guide/commands/toolchain/index.md "Edit this page") `toolchain` =========== Helper utility to manage Python toolchains. The following subcommands exist: * [`fetch`](fetch/) : fetches a toolchain * [`list`](list/) : lists all registered toolchains * [`register`](register/) : register a Python binary as custom toolchain * [`remove`](remove/) : removes or uninstalls a toolchain Back to top --- # fetch - Rye [](https://github.com/astral-sh/rye/edit/main/docs/guide/commands/toolchain/fetch.md "Edit this page") `fetch` ======= Fetches a Python interpreter for the local machine. This command is available under the aliases `rye fetch` and `rye toolchain fetch`. As of Rye 0.31.0 toolchains are always fetched without build info. This means that in the folder where toolchains are stored only the interpreter is found. For more information see [Fetching Toolchains](../toolchains/index.md#build-info) . Example ------- Fetch a specific version of Python: `$ rye fetch 3.8.13 Downloading [[email protected]](/cdn-cgi/l/email-protection) Checking checksum Unpacking Downloaded [[email protected]](/cdn-cgi/l/email-protection)` To fetch the pinned version of Python you can leave out the argument: `$ rye fetch Downloading [[email protected]](/cdn-cgi/l/email-protection) Checking checksum Unpacking Downloaded [[email protected]](/cdn-cgi/l/email-protection)` To fetch a version of Python into a specific location rather than rye's interpreter cache: `$ rye fetch [[email protected]](/cdn-cgi/l/email-protection) --target-path=my-interpreter` Arguments --------- * `[VERSION]`: The version of Python to fetch. If no version is provided, the requested version will be fetched. Options ------- * `-f, --force`: Fetch the Python toolchain even if it is already installed. * `--target-path` ``: Fetches the Python toolchain into an explicit location rather * `--build-info`: Fetches with build info * `--no-build-info`: Fetches without build info * `-v, --verbose`: Enables verbose diagnostics * `-q, --quiet`: Turns off all output * `-h, --help`: Print help (see a summary with '-h') Back to top --- # list - Rye [](https://github.com/astral-sh/rye/edit/main/docs/guide/commands/toolchain/list.md "Edit this page") `list` ====== List all registered toolchains. It can list the toolchains which are installed as well as toolchains which can be downloaded if `--include-downloadable` is passed. Example ------- List installed toolchains: `$ rye toolchain list [[email protected]](/cdn-cgi/l/email-protection) (/Users/username/.rye/py/[[email protected]](/cdn-cgi/l/email-protection) /install/bin/python3) [[email protected]](/cdn-cgi/l/email-protection) (/Users/username/.rye/py/[[email protected]](/cdn-cgi/l/email-protection) /install/bin/python3)` Lists downloadable toolchains: `$ rye toolchain list --include-downloadable [[email protected]](/cdn-cgi/l/email-protection) (/Users/mitsuhiko/.rye/py/[[email protected]](/cdn-cgi/l/email-protection) /install/bin/python3) [[email protected]](/cdn-cgi/l/email-protection) (downloadable) [[email protected]](/cdn-cgi/l/email-protection) (downloadable) ...` Arguments --------- _no arguments_ Options ------- * `--include-downloadable`: Also include non installed, but downloadable toolchains * `--format `: Request parseable output format \[possible values: json\] * `-h, --help`: Print help Back to top --- # register - Rye [](https://github.com/astral-sh/rye/edit/main/docs/guide/commands/toolchain/register.md "Edit this page") `register` ========== Register a Python binary as custom toolchain. Rye by default will automatically download Python releases from the internet. However it's also possible to register already available local Python installations. This allows you to use rye with self compiled Pythons. The name of the toolchain is auto detected (eg: `cpython`, `pypy` etc.) To unregister use the [`remove`](../remove/) command. Example ------- `$ rye toolchain register /opt/homebrew/Cellar/[[email protected]](/cdn-cgi/l/email-protection) /3.10.6_1/bin/python3.10 Registered /opt/homebrew/Cellar/[[email protected]](/cdn-cgi/l/email-protection) /3.10.6_1/bin/python3.10 as [[email protected]](/cdn-cgi/l/email-protection)` Arguments --------- * ``: Path to the python binary that should be registered Options ------- * `-n, --name `: Name of the toolchain. If not provided a name is auto detected. * `-h, --help`: Print help (see a summary with '-h') Back to top --- # remove - Rye [](https://github.com/astral-sh/rye/edit/main/docs/guide/commands/toolchain/remove.md "Edit this page") `remove` ======== Removes or uninstalls a toolchain. Example ------- `$ rye toolchain remove 3.9.5 Removed installed toolchain [[email protected]](/cdn-cgi/l/email-protection)` Arguments --------- * `` The version of Python to remove. Options ------- * `-f, --force`: Force removal even if the toolchain is in use * `-h, --help`: Print help (see a summary with '-h') Back to top --- # Overview - Rye [](https://github.com/astral-sh/rye/edit/main/docs/guide/commands/tools/index.md "Edit this page") `tools` ======= Helper utility to manage global tool installations. * [`install`](install/) : installs a tool globally. * [`uninstall`](uninstall/) : uninstalls a globally installed tool. * [`list`](list/) : lists all globally installed tools. Back to top --- # install - Rye [](https://github.com/astral-sh/rye/edit/main/docs/guide/commands/tools/install.md "Edit this page") `install` ========= Installs a package as global tool. This command has two names to `rye tools install` and `rye install`. This can be used to install useful Python scripts globally into it's own separated virtualenv. For instance if you want to use the `black` formatter you can install it once. Normally only scripts installed by the top level dependency are installed. In some cases you might also want to install commands from sub-dependencies. In that case pass those dependencies with `--include-dep`. For more information see [Tools](/guide/tools/) . Example ------- `$ rye tools install pycowsay Looking in indexes: https://pypi.org/simple/ Collecting pycowsay Downloading pycowsay-0.0.0.2-py3-none-any.whl.metadata (965 bytes) Downloading pycowsay-0.0.0.2-py3-none-any.whl (4.0 kB) Installing collected packages: pycowsay Successfully installed pycowsay-0.0.0.2 Installed scripts: - pycowsay $ pycowsay "Great Stuff" ----------- < Great Stuff > ----------- \ ^__^ \ (oo)\_______ (__)\ )\/\ ||----w | || ||` Arguments --------- * `...`: The package to install as PEP 508 requirement string. Options ------- * `--git `: Install the given package from this git repository * `--url `: Install the given package from this URL * `--path `: Install the given package from this local path * `--absolute`: Force non interpolated absolute paths * `--tag `: Install a specific tag * `--rev `: Update to a specific git rev * `--branch `: Update to a specific git branch * `--features `: Adds a dependency with a specific feature * `--include-dep `: Include scripts from a given dependency * `--extra-requirement `: Additional dependencies to install that are not declared by the main package * `-p, --python `: Optionally the Python version to use * `-f, --force`: Force install the package even if it's already there * `-v, --verbose`: Enables verbose diagnostics * `-q, --quiet`: Turns off all output * `-h, --help`: Print help (see a summary with '-h') Back to top --- # Overview - Rye [](https://github.com/astral-sh/rye/edit/main/docs/guide/commands/self/index.md "Edit this page") `self` ====== Command to manage Rye itself. * [`completion`](completion/) : Generates a completion script for Rye. * [`update`](update/) : Performs an update of Rye. * [`uninstall`](uninstall/) : Uninstalls Rye again. Back to top --- # completion - Rye [](https://github.com/astral-sh/rye/edit/main/docs/guide/commands/self/completion.md "Edit this page") `completion` ============ Generates a completion script for a shell Example ------- Generate a completion script for zsh and load it: `$ eval "$(rye self completion -s zsh)"` Arguments --------- _no arguments_ Options ------- * `-s, --shell `: The shell to generate a completion script for (defaults to 'bash') \[possible values: `bash`, `elvish`, `fish`, `powershell`, `zsh`, `nushell`\] * `-h, --help`: Print help (see a summary with '-h') Back to top --- # uninstall - Rye [](https://github.com/astral-sh/rye/edit/main/docs/guide/commands/tools/uninstall.md "Edit this page") `uninstall` =========== Uninstalls an already installed global tool. This command has two names to `rye tools uninstall` and `rye uninstall`. For more information see [Tools](/guide/tools/) . Example ------- `$ rye tools uninstall pycowsay Uninstalled pycowsay` Arguments --------- * ``: The package to uninstall. Options ------- * `-v, --verbose`: Enables verbose diagnostics * `-q, --quiet`: Turns off all output * `-h, --help`: Print help (see a summary with '-h') Back to top --- # list - Rye [](https://github.com/astral-sh/rye/edit/main/docs/guide/commands/tools/list.md "Edit this page") `list` ====== Lists all already installed global tools. For more information see [Tools](/guide/tools/) . Example ------- List installed tools: `$ rye tools list pycowsay` List installed tools with version: `$ rye tools list --include-version pycowsay 0.0.0.2 ([[email protected]](/cdn-cgi/l/email-protection) )` Arguments --------- _no arguments_ Options ------- * `-s, --include-scripts`: Show all the scripts installed by the tools changed in **0.26.0** Renamed from `-i, --include-scripts` to `-s, --include-scripts`. * `-v, --include-version`: Show the version of tools changed in **0.26.0** Renamed from `-v, --version-show` to `-v, --include-version`. * `-h, --help`: Print help Back to top --- # update - Rye [](https://github.com/astral-sh/rye/edit/main/docs/guide/commands/self/update.md "Edit this page") `update` ======== Performs an update of rye. This can install updates from the latest release binaries or trigger a manual compilation of Rye if Rust is installed. Example ------- Update to the latest version: `$ rye self update` Update (or downgrade) to a specific version: `$ rye self update --version 0.20` Compile a specific revision: `$ rye self update --rev 08910bc9b3b7c72a3d3ac694c4f3412259161477` Compile latest development version: `$ rye self update --branch main` Arguments --------- _no arguments_ Options ------- * `--version `: Update to a specific version * `--tag `: Update to a specific tag * `--rev `: Update to a specific git rev * `--branch `: Update to a specific git branch * `--force`: Force reinstallation * `-h, --help`: Print help (see a summary with '-h') Back to top --- # uninstall - Rye [](https://github.com/astral-sh/rye/edit/main/docs/guide/commands/self/uninstall.md "Edit this page") `uninstall` =========== Uninstalls rye again. Note that this leaves a trace `.rye` folder behind with an empty `env` file. You also need to remove the sourcing of that script from your `.profile` file. Example ------- Uninstall rye without asking: `$ rye self uninstall --yes` Arguments --------- _no arguments_ Options ------- * `-y, --yes`: Do not prompt and uninstall. * `-h, --help`: Print help (see a summary with '-h') Back to top --- # uninstall - Rye [](https://github.com/astral-sh/rye/edit/main/docs/guide/commands/uninstall.md "Edit this page") `uninstall` =========== Uninstalls an already installed global tool. This command has two names to `rye tools uninstall` and `rye uninstall`. For more information see [Tools](/guide/tools/) . Example ------- `$ rye tools uninstall pycowsay Uninstalled pycowsay` Arguments --------- * ``: The package to uninstall. Options ------- * `-v, --verbose`: Enables verbose diagnostics * `-q, --quiet`: Turns off all output * `-h, --help`: Print help (see a summary with '-h') Back to top --- # version - Rye [](https://github.com/astral-sh/rye/edit/main/docs/guide/commands/version.md "Edit this page") `version` ========= Get or set project version. Note that this does not refer to the version of Rye itself but the version that is set in the `pyproject.toml` file. Example ------- Get the current version: `$ rye version 0.1.0` Bump the version by minor: `$ rye version -b minor version bumped to 0.2.0` Set to a specific version: `$ rye version 1.0.0 version set to 1.0.0` Arguments --------- * `[VERSION]`: the version to set Options ------- * `-b, --bump `: automatically bump the version in a specific way (`major`, `minor` or `patch`) * `-h, --help`: Print help (see a summary with '-h') Back to top --- # Toolchain Management - Rye [](https://github.com/astral-sh/rye/edit/main/docs/guide/toolchains/index.md "Edit this page") Toolchain Management ==================== Rye is unique in that it does not use system Python installations. Instead it downloads and manages Python installations itself (called toolchains). Today there are three types of toolchains supported by Rye and they require some understanding: * [**Portable CPython**](cpython/) : Rye will itself download portable builds of CPython for most of its needs. These are fetched from [indygreg/python-build-standalone](https://github.com/indygreg/python-build-standalone) * [**Official PyPy Builds**](pypy/) : PyPy is supported from the official release builds. * [**Custom Local Toolchains**](#registering-toolchains) : locally installed Python interpreters can be registered with Rye. Afterwards, they can be used with any Rye managed project. Pinning Toolchains ------------------ To make a project use a specific toolchain write the name of the toolchain into the `.python-version` file or use the `pin` command. For pinning `cpython` the `cpython@` prefix can be omitted. `rye pin [[email protected]](/cdn-cgi/l/email-protection)` Pinning a downloadable version means that Rye will automatically fetch it when necessary. By default, toolchains are pinned to a precise version. This means that even if you write `rye pin [[email protected]](/cdn-cgi/l/email-protection) `, a very specific version of cpython is written into the `.python-version` file. With Rye 0.5.0 onwards it's possible to perform "relaxed" pins: `rye pin --relaxed [[email protected]](/cdn-cgi/l/email-protection)` This will then persist `3.11` in the `.python-version` file and Rye will use the latest available compatible version for the virtual environment. changed in **0.5.0** Relaxed pinning with `rye pin --relaxed` was added. Non Native Architectures ------------------------ new in **0.14.0** Support for fetching and pinning of non-native architectures was added. By default, the pin is for the architecture of the running machine. This means that if you pin `[[email protected]](/cdn-cgi/l/email-protection) ` on a mac with aarch64 architecture, you will use a cpython interpreter of that CPU architecture. A different architecture can be selected by adding `-{arch}` to the python family name. So for instance to force a `x86_64` version you need to pin like this: `rye pin [[email protected]](/cdn-cgi/l/email-protection)` Note that such custom pins are not reflected in `pyproject.toml` but only `.python-version`. Listing Toolchains ------------------ To see which toolchains are installed, `rye toolchain list` prints a list: `rye toolchain list` `[[email protected]](/cdn-cgi/l/email-protection) (C:\Users\armin\.rye\py\[[email protected]](/cdn-cgi/l/email-protection) \install\python.exe) [[email protected]](/cdn-cgi/l/email-protection) (C:\Users\armin\.rye\py\[[email protected]](/cdn-cgi/l/email-protection) \python.exe)` To see which toolchains can be installed, additionally pass the `--include-downloadable`: `rye toolchain list --include-downloadable` Fetching Toolchains ------------------- Generally Rye automatically downloads toolchains, but they can be explicitly fetched with `rye toolchain fetch` (also aliased to `rye fetch`): `rye toolchain fetch [[email protected]](/cdn-cgi/l/email-protection)` Starting with Rye 0.19.0 the argument to `fetch` is inferred from the current pin. This means you can also fetch as follows: `rye pin 3.10 rye fetch` Toolchains are fetched from two sources: * [Indygreg's Portable Python Builds](https://github.com/indygreg/python-build-standalone) for CPython * [PyPy.org](https://www.pypy.org/) for PyPy You can also fetch toolchains into a specific location. In this case the interpreter is not stored where Rye normally consults it, but in a specific location. Rye will then not be able to use it unless it's manually registered. This however can be useful for debugging or advanced setups: `rye toolchain fetch [[email protected]](/cdn-cgi/l/email-protection) --target-path=my-interpreter` If you want to use rye interpreter fetching without installing rye, you might want to export the `RYE_NO_AUTO_INSTALL` environment variable and set it to `1` as otherwise the installer will kick in. Registering Toolchains ---------------------- Additionally, it's possible to register an external toolchain with the `rye toolchain register` command. `rye toolchain register /path/to/python` The name of the toolchain is picked based on the interpreter. For instance linking a regular cpython installation will be called `cpython@version`, whereas linking pypy would show up as `pypy@version`. From Rye 0.5.0 onwards `-dbg` is appended to the name of the toolchain if it's a debug build. To override the name you can pass `--name`: `rye toolchain register --name=custom /path/to/python` Removing Toolchains ------------------- To remove an already fetched toolchain run `rye toolchain remove`. Note that this also works for linked toolchains: `rye toolchain remove [[email protected]](/cdn-cgi/l/email-protection)` Warning Removing an actively used toolchain will render the virtualenvs that refer to use broken. Build Info ---------- new in **0.31.0** Prior to Rye 0.31.0 the Python installations were fetched with build infos. You can see this because the folder structure in `~/.rye/py/INTERPRETER` is a bit different. Rather than finding `[[email protected]](/cdn-cgi/l/email-protection) /bin/python3` there you will instead have an extra `install` folder (`[[email protected]](/cdn-cgi/l/email-protection) /install/bin/python3`) alongside a `build` folder containing the intermediate build outputs. Starting with 0.31.0 the build info is removed by default. If you want to get it back, you can explicitly fetch with `--build-info` or you can set the `behavior.fetch-with-build-info` config flag to true: `rye config --set-bool behavior.fetch-with-build-info=true` Back to top --- # Portable CPython - Rye [](https://github.com/astral-sh/rye/edit/main/docs/guide/toolchains/cpython.md "Edit this page") Portable CPython ================ Rye is capable (and prefers) to download its own Python distribution over what you might already have on your computer. For CPython, the [indygreg/python-build-standalone](https://github.com/indygreg/python-build-standalone) builds from the PyOxidizer project are used. The motivation for this is that it makes it easy to switch between Python versions, to have a common experience across different Rye users and to avoid odd bugs caused by changes in behavior. Unfortunately Python itself does not release binaries (or the right types of binaries) for all operating systems which is why Rye leverages the portable Python builds from PyOxidizer. Unlike many other Python versions you can install on your computer are non-portable which means that if you move them to a new location on your machine, or you copy it onto another computer (even with the same operating system) they will no longer run. This is undesirable for what Rye wants to do. For one we want the same experience for any of the Python developers, no matter which operating system they used. Secondly we want to enable self-contained Python builds later, which requires that the Python installation is portable. To achieve this, the Python builds we use come with some changes that are different from a regular Python build. Limitations ----------- The following changes to a regular Python versions you should be aware of: * `libedit` instead of `readline`: unfortunately `readline` is GPLv3 licensed and this is a hazard for redistributions. As such, the portable Python builds link against the more freely licensed `libedit` instead. * `dbm.gnu` is unavailable. This is a rather uncommonly used module and the standard library provides alternatives. Additionally due to how these builds are created, there are some other quirks you might run into related to terminal support or TKinter. Some of these issues are collected in the [FAQ](../../faq/) . Additionally, the Python Standalone Builds have a [Behavior Quirks](https://gregoryszorc.com/docs/python-build-standalone/main/quirks.html) page. Sources ------- Portable CPython builds are downloaded from GitHub ([indygreg/python-build-standalone/releases](https://github.com/indygreg/python-build-standalone/releases) ) and SHA256 hashes are generally validated. Some older versions might not have hashes available in which case the validation is skipped. Usage ----- When you pin a Python version to `[[email protected]](/cdn-cgi/l/email-protection) ` (or just `major.minor.patch`) then Rye will automatically download the right version for you whenever it is needed. If a [custom toolchain](../#registering-toolchains) has already been registered with that name and version, that this is used instead. Back to top --- # Tools - Rye [](https://github.com/astral-sh/rye/edit/main/docs/guide/tools.md "Edit this page") Tools ===== Rye supports global tool installations. This for instance allows you to install tools like `black` or `ruff` globally. Installing Tools ---------------- Use the [`rye tools install`](../commands/tools/install/) (aliased to [`rye install`](../commands/install/) ) command to install a tool globally with a shim: `rye install ruff` Afterwards the tool is installed into `~/.rye/tools/ruff` and the necessary shims are placed in `~/.rye/shims`. changed in **0.4.0** The `install` command now considers custom sources configured in the `config.toml` file. For more information see [Dependency Sources](../sources/) . Extra Requirements ------------------ Some tools do not declare all of their dependencies since they might be optional. In some cases these can be declared by passing extra features to the installer: `rye install black --features colorama` If dependencies are not at all specified, then they can be provided with `--extra-requirement`. This is particularly sometimes necessary if the tool uses `pkg_resources` (part of `setuptools`) but forgets to declare that dependency: `rye install gradio --extra-requirement setuptools` Listing Tools ------------- If you want to see which tools are installed, you can use `rye tools list`: `rye tools list` `black black blackd ruff ruff` To also see which scripts those tools provide, also pass `--include-scripts` `rye tools list --include-scripts` Uninstalling Tools ------------------ To uninstall a tool again, use `rye tools uninstall` (aliased to `rye uninstall`): `rye uninstall black` Back to top --- # PyPy - Rye [](https://github.com/astral-sh/rye/edit/main/docs/guide/toolchains/pypy.md "Edit this page") PyPy ==== [PyPy](https://www.pypy.org/) is supported as alternative Python distribution. Like the portable CPython builds it's downloaded automatically. The name for PyPy distributions is `pypy`. Limitations ----------- PyPy has some limitations compared to regular Python builds when it comes to working with Rye. Most specifically PyPy uses some internal pypi dependencies and you might notice warnings show up when syching. PyPy also lags behind regular Python installations quite a bit these days so you likely need to target older Python packages. Sources ------- PyPy builds are downloaded from [downloads.python.org](https://downloads.python.org/pypy/) . Usage ----- When you pin a Python version to `[[email protected]](/cdn-cgi/l/email-protection) ` then Rye will automatically download the right version for you whenever it is needed. If a [custom toolchain](../#registering-toolchains) has already been registered with that name and version, that this is used instead. Note that the version refers to the PyPy **CPython** version. That means for instance that PyPy 7.3.11 is identified as `[[email protected]](/cdn-cgi/l/email-protection) ` as this is the Python version it provides. As PyPy also lacks builds for some CPU architectures, not all platforms might provide the right PyPy versions. Back to top --- # Email Protection | Cloudflare Please enable cookies. Email Protection ================ You are unable to access this email address astral.sh ----------------------------------------------------- The website from which you got to this page is protected by Cloudflare. Email addresses on that page have been hidden in order to keep them from being accessed by malicious bots. **You must enable Javascript in your browser in order to decode the e-mail address**. If you have a website and are interested in protecting it in a similar way, you can [sign up for Cloudflare](https://www.cloudflare.com/sign-up?utm_source=email_protection) . * [How does Cloudflare protect email addresses on website from spammers?](https://support.cloudflare.com/hc/en-us/articles/200170016-What-is-Email-Address-Obfuscation-) * [Can I sign up for Cloudflare?](https://support.cloudflare.com/hc/en-us/categories/200275218-Getting-Started) Cloudflare Ray ID: **92883617488d3b0e** • Your IP: Click to reveal 54.237.218.47 • Performance & security by [Cloudflare](https://www.cloudflare.com/5xx-error-landing) --- # fetch - Rye [](https://github.com/astral-sh/rye/edit/main/docs/guide/commands/fetch.md "Edit this page") `fetch` ======= Fetches a Python interpreter for the local machine. This command is available under the aliases `rye fetch` and `rye toolchain fetch`. As of Rye 0.31.0 toolchains are always fetched without build info. This means that in the folder where toolchains are stored only the interpreter is found. For more information see [Fetching Toolchains](../../toolchains/#build-info) . Example ------- Fetch a specific version of Python: `$ rye fetch 3.8.13 Downloading [[email protected]](/cdn-cgi/l/email-protection) Checking checksum Unpacking Downloaded [[email protected]](/cdn-cgi/l/email-protection)` To fetch the pinned version of Python you can leave out the argument: `$ rye fetch Downloading [[email protected]](/cdn-cgi/l/email-protection) Checking checksum Unpacking Downloaded [[email protected]](/cdn-cgi/l/email-protection)` To fetch a version of Python into a specific location rather than rye's interpreter cache: `$ rye fetch [[email protected]](/cdn-cgi/l/email-protection) --target-path=my-interpreter` Arguments --------- * `[VERSION]`: The version of Python to fetch. If no version is provided, the requested version will be fetched. Options ------- * `-f, --force`: Fetch the Python toolchain even if it is already installed. * `--target-path` ``: Fetches the Python toolchain into an explicit location rather * `--build-info`: Fetches with build info * `--no-build-info`: Fetches without build info * `-v, --verbose`: Enables verbose diagnostics * `-q, --quiet`: Turns off all output * `-h, --help`: Print help (see a summary with '-h') Back to top --- # `list` - Rye [](https://github.com/astral-sh/rye/edit/main/docs/guide/commands/list.md "Edit this page") `list` ====== new in **0.24.0** Prints a list of installed dependencies. Example ------- `$ rye list asgiref==3.7.2 blinker==1.7.0 click==8.1.7 Flask @ git+https://github.com/pallets/flask@4df377cfbfc1d15e962a61c18920b22aebc9aa41 itsdangerous==2.1.2 Jinja2==3.1.3 MarkupSafe==2.1.4 Werkzeug==3.0.1` Arguments --------- _no arguments_ Options ------- * `--pyproject`: Use this `pyproject.toml` file * `-h, --help`: Print help (see a summary with '-h') Back to top --- # FAQ - Rye [](https://github.com/astral-sh/rye/edit/main/docs/guide/faq.md "Edit this page") FAQ === This section should cover some commonly asked questions. If you do not find an answer here, consider reaching out to the [community](../../community/) . How Do I Install PyTorch? ------------------------- PyTorch requires setting up manual [sources](../sources) as it's not installed via PyPI. These sources can be set up in [`pyproject.toml`](../pyproject/) for a simple project or globally in the [config](../config/) . * **Option 1:** `pyproject.toml` `[[tool.rye.sources]] name = "pytorch" url = "https://download.pytorch.org/whl/cpu"` * **Option 2:** `~/.rye/config.toml` `[[sources]] name = "pytorch" url = "https://download.pytorch.org/whl/cpu"` Afterwards you can add pytorch as you would expect: `rye add torch torchvision torchaudio` Windows Developer Mode ---------------------- Rye does not require symlinks but it works significantly better with them. On Windows support for symlinks is restricted to privileged accounts. The reason for this is that Symlinks were a late addition to Windows and some applications are not developed with them in mind which can cause misbehavior or in the worst case security issues in those applications. Symlinks support however is enabled when the "developer mode" is activated on modern Windows versions. Enabling "developer mode" has changed in later version of Windows. For older versions: 1. Press Win+I to open the settings 2. In the settings dialog click on "Privacy & security" 3. In the "Security" section click on "For developers" 4. Enable the toggle "Developer Mode" 5. In the "Use developer features" dialog confirm by clicking "Yes". In more modern versions: 1. Press Win+I to open the settings 2. In the settings dialog click on "System" 3. In the "System" section click on "For developers" 4. Enable the toggle "Developer Mode" 5. In the "Use developer features" dialog confirm by clicking "Yes". What happens if I don't enable it? Enabling symlinks is not strictly required as Rye automatically falls back to hardlinks and junction points. However not having symlinks enabled will ultimately result in a worse user experience for the following reasons: * Custom toolchain registration uses proxy files rather than actual symlinks which means that the executables in the `.rye\py` path are non executable. * All shims will be installed as hardlinks. This can cause issues when upgrading Rye while Python is in use. These hardlinks will also continue to point to older Rye executables creating more hard drive usage. * Virtualenvs will be created with copies rather than symlinks. * Junction points are used where symlinks to directories are otherwise used. Some tools might accidentally not detect junction points which can cause deletion of virtualenvs to accidentally also delete or destroy the toolchain behind it. Missing Shared Libraries on Linux --------------------------------- The Python builds that Rye uses require a Linux installation compatible to the Linux Standard Base Core Specification (LSB). Unfortunately not all Linux distributions are strictly adhering to that specification out of the box. In particularly the library `libcrypt.so.1` is commonly not installed on certain Linux distributions but the `_crypt` standard library module depends on it. Depending on the Linux distributions you need to run different commands to resolve this: * archlinux: `pacman -S libxcrypt-compat` * CentOS/RedHat: `dnf install libxcrypt-compat` There have also been reports of an error being generated at installation time despite `libcrypt.so.1` being installed when a different `ldd` (eg: Homebrew) shadows the system one. In that case try the installation again after giving the default one higher priority in the \`PATH: `export PATH="/usr/bin:$PATH" curl -sSf https://rye.astral.sh/get | bash` References to Build-Time Paths ------------------------------ The prefers using standalone Python builds. As Python historically is not much accommodating to portable builds there are various limitations still with this approach. One of them is that built Python distributions capture some absolute paths and other build-time configuration. These file paths are then often used by build tools to invoke C compilers. For instance you might run into a compiler error like `error: stdio.h: No such file or directory` when building C extensions. There is no known solution to this problem today other than [registering a non portable toolchain](../toolchains/#registering-toolchains) . This issue is inherited from `python-build-standalone` and more information can be found in the documentation: [References to Build-Time Paths](https://gregoryszorc.com/docs/python-build-standalone/main/quirks.html#references-to-build-time-paths) . There is also an open Rye issue for it: [Issue #621](https://github.com/astral-sh/rye/issues/621) . TKinter Support --------------- TKinter uses TCL behind the scenes. Unfortunately this also means that some runtime support is required. This runtime support is provided by the portable Python builds, however the way TCL is initialized on macOS and Linux won't find these files in virtualenvs. Newer versions of Rye will automatically export the `TCL_LIBRARY` and `TK_LIBRARY` environment variables for you in a manner very similar to this: `import os import sys os.environ["TCL_LIBRARY"] = sys.base_prefix + "/lib/tcl8.6" os.environ["TK_LIBRARY"] = sys.base_prefix + "/lib/tk8.6"` Python Interactive Prompt Input Messed Up ----------------------------------------- The Python builds that Rye uses are compiled against `libedit` rather than `readline` for licensing reasons. You might run into unicode issues on input as a result of this due to limitations in `libedit`. In some cases though you might also discover that the backspace key does not work or arrow keys don't work as expected. This can be because the _terminfo_ database cannot be found. For solutions to this issue, read the [behavior quirks guide](https://gregoryszorc.com/docs/python-build-standalone/main/quirks.html) in the Standalone Python Builds documentation for solutions. Can I use Rye Alongside Other Python Installations? --------------------------------------------------- Rye given its experimental nature does not want to disrupt already existing Python workflows. As such using it alongside other Python installations is intentionally supported. Even if the Rye shims come first on the `PATH`, Rye will automatically resolve to a different Python installation on the search path when invoked in a folder that contains a non Rye managed project. As such the answer is a clear **yes!** Musl/Alpine Support ------------------- When bootstrapping it can happen that you are running into a confusing error like "No such file or directory (os error 2)". This can happen on MUSL based Linux systems like Alpine. The reason for this is that Rye downloads distribution independent Python interpreters which are not compatible with Linux systems that do not use glibc. The solution today is to install Python via other means and to install Rye with a custom `RYE_TOOLCHAIN`. For more information see [Customized Installation](/guide/installation/#customized-installation) Wheels Appear to be Missing Files --------------------------------- You might be encountering missing files in wheels when running `rye build` and you are using hatchling. The reason for this is that `rye build` uses "[build](https://pypi.org/project/build/) " behind the scenes to build wheels. There are two build modes and in some cases the wheel is first built from an sdist. So if your sdists does not include the necessary data files, the resulting wheel will also be incorrect. This can be corrected by adding the files to the `include` in the hatch config for sdists. For instance the following lines added to `pyproject.toml` will add the data files in `my_package` and all the tests to the sdist from which the wheel is built: `[tool.hatch.build.targets.sdist] include = ["src/my_package", "tests"]` Can I Relocate Virtualenvs? --------------------------- Rye very intentionally places the virtualenv (`.venv`) in the root folder of the workspace. Relocations of virtualenvs is not supported. This is a very intentional decision so that tools do not need to deal with various complex alternatives and can rely on a simple algorithm to locate it. This is a form of convention over configuration and can also assist editor integrations. There are some known downsides of this. For instance if you are placing your projects in Dropbox, it would cause this folder to synchronize. As a way to combat this, Rye will automatically mark the virtualenv with the necessary flags to disable cloud sync of known supported cloud synchronization systems. For override this behavior you can set the `behavior.venv-mark-sync-ignore` configuration key to `false`. Why Does Rye Contain Trojan "Bearfoos"? --------------------------------------- Unfortunately Windows likes to complain that Rye contains the trojan "Win32/Bearfoos.A!ml". This seems to be something that happens to a few programs written in Rust every once in a while because the compiler spits out some bytes that have been associated with Trojans written in Rust. It can be ignored. For more information see the discussion [Windows Bearfoos virus associated with rye](https://github.com/astral-sh/rye/issues/468) . Back to top ---