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 file +in the repository.
+ + +Released on 2024-08-20.
+add.md by @mikkelam in https://github.com/astral-sh/rye/pull/1322v0.3.0 by @github-actions in https://github.com/astral-sh/rye/pull/1332Released on 2024-08-01.
+rye add and rye remove to create proper tool.rye section for --dev and --exclude flags by @flyaroundme in https://github.com/astral-sh/rye/pull/1256uninstall_cmd on Windows by @250h in https://github.com/astral-sh/rye/pull/1153--index-url before --extra-index-url by @charliermarsh in https://github.com/astral-sh/rye/pull/1278rye.exe by @charliermarsh in https://github.com/astral-sh/rye/pull/1286v0.2.33 by @github-actions in https://github.com/astral-sh/rye/pull/1303v24.2.0 by @charliermarsh in https://github.com/astral-sh/rye/pull/1304Released on 2024-07-20.
+-d for rye remove --dev by @nikhilweee in https://github.com/astral-sh/rye/pull/1239v0.2.27 by @github-actions in https://github.com/astral-sh/rye/pull/12323.12.4 by @github-actions in https://github.com/astral-sh/rye/pull/1230.python-version in Rye builds by @charliermarsh in https://github.com/astral-sh/rye/pull/1250v0.5.4 by @charliermarsh in https://github.com/astral-sh/rye/pull/1251Released on 2024-07-07.
+Released on 2024-06-24.
+--pre when auto-syncing by @charliermarsh in https://github.com/astral-sh/rye/pull/1107rye-up.com to rye.astral.sh by @charliermarsh in https://github.com/astral-sh/rye/pull/1113powershell) by @charliermarsh in https://github.com/astral-sh/rye/pull/1125config.toml error messages by @zys864 in https://github.com/astral-sh/rye/pull/1155Released on 2024-05-20.
+.com) binaries on Windows by @mataha in https://github.com/astral-sh/rye/pull/1091use-uv = true in no-prompt mode by @charliermarsh in https://github.com/astral-sh/rye/pull/1098Released on 2024-04-24.
+Ensure files created by rye init, such as pyproject.toml and initial python files end with a newline. #979
Add --refresh argument on -f. #994
Preserve trailing newline in templates. #979
+Update uv to 0.1.37. #980
+Allow comments in .python-version. #1038
Update Python releases to include 3.12.3 et al. #1022
+Released on 2024-03-29
+Update uv to 0.1.26. #924
+Always create .gitignore file in rye init. #919
Prevent rye fetch --force from removing a target directory that is not a Python installation. #921
rye list always prints the currently installed packages even this project is not managed by Rye. #940
Fix error on using -v or -q with rye fmt or rye lint. #959
Fix rye fetch detection of registered toolchain. #931
+Ignore build-system configuration for virtual projects. #929
+Released on 2024-03-22
+Update uv to 0.1.23. #916
+Allow rye publish working outside of project. #910
rye test --quiet no longer implies --no-capture. #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/cpython@3.11.1/install/bin/python3
+ it will now reside at ~/.rye/py/cpython@3.11.1/bin/python3. #917
Installer now recommends uv over pip-tools. #918
Released on 2024-03-19
+Fix incorrect flag passing of rye test -q and -v. #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
Fix rye add m --path ./m causing a panic on windows. #897
Released on 2024-03-11
+Trap panics and silence bad pipe errors. #862
+Updating rye will now also ensure that the self-venv is updated. Previously
+ this was deferred until the next sync. #863
The self update command now accepts --branch. #864
Fixed an issue that caused pip-tools to not update. #865
+Updates build and certifi. #866
Released on 2024-03-07
+--skip-existing is now available with Rye's publish command. #831
Bumped ruff to 0.3.0. #821
The init command now generates a script with the name of the
+ project rather than hello. #801
Retain markers when adding dependencies with features when uv is used. #807
+Fixed a bug that caused repeated syncs not to recall all previous options. #830
+Report self-python version in --version. #843
Fixes a bug where rye config would not create the RYE_HOME folder if needed. #844
rye add now retains version and URL for the requirements when uv is used. #846
Added a rye test command which invokes pytest. #847
Released on 2024-02-26
+rye now uses uv to bootstrap its internal packages and tools. #754
rye no longer fails if an incorrect VIRTUAL_ENV environment
+ variable is exported. #766
Added latest Python builds. #771
+When uv is used the prompt is now set to the project name. #773
Allow rye fetch --force to force re-fetch a downloaded toolchain. #778
Fixed a panic when adding a package to a virtual project. #783
+Bumped uv to 0.1.11. #790
Released on 2024-02-23
+init now supports --script and --lib to generate a script or library project. #738
Fixed rye config --show-path abort with an error. #706
Bumped ruff to 0.2.2. #700
Prevent rye toolchain remove from removing the currently active toolchain. #693
Sync latest PyPy releases. #683
+Fixes an issue where when uv is enabled, add did not honor custom sources. #720
When uv is enabled, rye will now automatically sync on add and remove. #677
Rename rye tools list flags: -i, --include-scripts to -s, --include-scripts and -v, --version-show to -v, --include-version. #722
Released on 2024-02-19
+Improved the error message if config is invoked without arguments. #660
When uv is enabled, rye add now uses uv instead of unearth
+ internally. #667
The installer now has slightly better wording for what the shims are doing. #669
+uv can now also be enabled on windows. #675
Removed the unsupported and un-used arch parameter from fetch. #681
Fixed the -q parameter not working for the init command. #686
rye tools list shows broken tools if the toolchain was removed. #692
Configure the ruff cache directory to be located within the workspace root. #689
+Use default toolchain to install tools. #666
+rye --version now shows if uv is enabled. #699
Released on 2024-02-15
+Added new rye list command and deprecated rye show --installed-deps which it replaces. #656
Added experimental support for uv. #657
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
Fixed a bug that caused warnings about unsupported operations to be shown on Linux. #634
+The venv sync marker is now only updated when a new virtualenv is created. #638
+Lockfiles now contain annotations. #643
+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
+Fixed a bug where pip-tools sometimes did not get initialized. #596
+Rye now prefers installed toolchains over newer latest toolchains unless + a precise pin is used. #598
+Removed the non functional shell command. #602
Upgraded internal unearth dependency which resolved an issue where
+ rye add tensorflow would not work. #614
The installer now supports RYE_TOOLCHAIN_VERSION. #606
rye init will no longer create packages with leading digits. #616
Rye now statically links vcruntime on Windows which no longer requires
+ the vs redist to be installed. #622
rye show now prints out which sources are configured for a project. #631
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
The rye installer now prompts for the default toolchain version if global shims + are enabled. #576
+The internal Python version was bumped to 3.12. #576
+The installer now can automatically add Rye to PATH on most UNIX environments. #580
Released on 2024-02-01
+Improved the error message when an update could not be performed because files + are in use. #550
+Rye now supports virtual projects. These are themselves not installed into the + virtualenv but their dependencies are. #551
+Update the Python internals (python external dependencies) to new versions. #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
Added rye fmt and rye lint commands to format and lint with
+ the help of Ruff. #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
+Upon installation Rye now prompts if global shims should be enabled. #566
+Add a warning about bugs to the shell command until the behavior has been
+ fixed. #567
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
Fixed an issue where rye init would pin a much too specific version in the .python-version
+ file that is generated. #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
Fixed a regression in 0.18 that caused the add command to fail. #547
Released on 2024-01-20
+Incorporate new Python builds. #535
+Disable revocation checks on windows to support corporate MITM proxies. #537
+Detect when a virtualenv relocates and automatically re-create it on sync. #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
When using global python shims, the .python-version file is now correctly
+ picked up in all cases. #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
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
Released on 2024-01-15
+Fixed default generated script reference. #527
+Correctly fall back to home folder if HOME is unset. #533
+Released on 2023-12-17
+By default a script with the name of the project is now also configured. #519
+Rye now configures hatchling better in rye init so that it works with
+ hatchling 1.19 and later. #521
Rye now detects the dummy Python shim that starts the windows store and + refuses to consider it. #486
+Released on 2023-10-04
+Released on 2023-10-03
+Released on 2023-10-03
+Released on 2023-10-01
+Add support for fetching alternative CPU architectures. #447
+The order of git submodule initialization was changed. This improves the
+ automatic author detection when includeIf is used. #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
The installer now detects fish and will spit out additional instructions
+ for configuring the shell.
Fix the wrong behavior when bump version. #454
+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.
Released on 2023-08-27
+Improve handling of the pth files for TCL on pypy. #409
+The rye tools list command now accepts -v to also print out the
+ versions of the installed tools. #396
Fixed parsing of versions by rye version. #397
Improved the help message for rye init. #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
Fixed an issue where the author email was incorrectly detected. #382
+The prompt of new virtualenvs is now set to the project name. #383
+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
When importing with rye init and no src folder exists, it will not be
+ created. #375
Added support for shell command on Windows. #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
The version command can show dynamic versions now. #355
rye add now properly checks some incompatible argument combinations. #347
There is now more toolchain validation. This better supports cases where + rye was interrupted during sync. #351
+Released on 2023-07-07
+Fixed a bug with rye init not operating correctly due to a argument conflict. #346
Scripts now support a PDM style call script type. #345
The init command is now capable of importing existing projects. #265
Fixed the global shim behavior on Windows. #344
+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
+rye add now accepts --pin to let one override the type of pin to use. #341
Added rye config to read and manipulate the config.toml file. #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
Renamed the config key default.dependency_operator to default.dependency-operator
+ and behavior.force_rye_managed to behavior.force-rye-managed. #338
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
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
rye install now lets you install dependencies into the tool's virtualenv
+ during installation that are undeclared via the new --extra-requirement
+ option. #326
Improved handling of relative path installations by setting PROJECT_ROOT
+ the same way as PDM does. #321
Workspaces will now never discover pyproject.toml files in any dot
+ directories. (Name starting with .) #329
Fixed rye build not working correctly on Windows. #327
Released on 2023-06-12
+rye sync and rye lock now accept --pyproject. #296
Added JSON output to rye toolchain list by adding --format=json. #306
rye version can bump version by --bump option now. #298
Fixed members not handled correctly in workspaces. #300
+Add --clean for build command. #297
Fixed an issue where pip was not invoked from the right working directory + causing issues for workspace installations. #292
+rye init now accepts --private to set the Private :: Do Not Upload classifier
+ that prevents uploads to PyPI. #291
Released on 2023-06-03
+Add version subcommand for rye. #285
Fixed rye pin pinning the wrong version. #288
Calling rye init on the root directory no longer fails. #274
rye run, show, pin, shell and build now take a --pyproject
+ argument. #232
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
The publish command now supports --yes to disable prompts. #270
When a Python debug build (Py_DEBUG) is registered as custom toolchain,
+ -dbg is automatically appended to the name by default. #269
lto+pgo builds are now preferred for the Python toolchain builds when + available. #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
Workspaces will no longer discover pyproject.toml files in virtualenvs
+ or .git folders. #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
Default build-system and license can be specified in global config. #244
+Fixed an issue where the init command would not let you create
+ flit based projects. #254
Resolve an error ("No such file or directory") shown after updates on + Linux machines. #252
+The built-in updater now validates checksums of updates when updates have + SHA-256 hashes available. #253
+init now accepts --no-pin to not create a .python-version file. #247
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
Virtualenvs on Unix are now created with a hack to pre-configure TCL and + TKinter. #233
+Fix invalid version error when using rye init with custom toolchain. #234
+Failed tool installations now properly clean up. #225
+Correctly swap the rye executable on windows when performing an update
+ to a git version via self update.
Released on 2023-05-27
+Support retrieving username and repository-url from credentials if not
+ provided for the publish command. #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
It's now possible to configure http and https proxies. #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
Add --username parameter for rye publish. #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
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
Support auto fix requires-python when there is a conflict. #160
+Added support for custom indexes. #199
+rye add no longer complains when a local version information is
+ in the version. #199
Released on 2023-05-22
+Fixed dev-dependencies not being installed when using workspace. #170
+init no longer creates invalid flit config. #195
Support direct references when adding a package. #158
+Fixed a bug with uninstall on Unix platforms. #197
+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
+Fixed an issue on macOS where the installer would die with "os error 24" + when directly piped to bash. #184
+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
Script declarations in pyproject.toml now permit chaining and custom
+ environment variables. #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 pypy@3.9.16 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.
+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:
+You can also reach out via Twitter or +Bluesky.
+Want to show that you are using Rye? Why not throw a badge into your project's README.md:
[](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:
+<a href="https://rye.astral.sh"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/rye/main/artwork/badge.json" alt="Rye" style="max-width:100%;"></a>
+To use Rye you need to have a pyproject.toml based Python project. For this guide you can
+create one with rye 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
+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.
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.
+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
+first.
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
+Use the remove command to remove a dependency from the project again.
rye remove flask
+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:
+. .venv/bin/activate
+.venv\Scripts\activate
+To deactivate it again run deactivate:
deactivate
+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
+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 will be generated with a
+[project.scripts] 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
+addAdds 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 command or pass
+--sync. To remove a dependency again use the remove command.
new in 0.26.0
+Added support for auto-sync and the --sync / --no-sync flags.
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
+<REQUIREMENTS>...: The package to add as PEP 508 requirement string. e.g. 'flask==2.2.3'--git <GIT>: Install the given package from this git repository
--url <URL>: Install the given package from this URL
--path <PATH>: Install the given package from this local path
--absolute: Force non interpolated absolute paths
--tag <TAG>: Install a specific tag
--rev <REV>: Update to a specific git rev
--branch <BRANCH>: Update to a specific git branch
--features <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 <OPTIONAL>: Add this to an optional dependency group
--pre: Include pre-releases when finding a package version
--pin <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)
buildBuilds 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.
+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.
no arguments
+--sdist: Build an sdist
--wheel: Build a wheel
-a, --all: Build all packages
-p, --package <PACKAGE>: Build a specific package
-o, --out <OUT>: An output directory (defaults to workspace/dist)
--pyproject <PYPROJECT_TOML>: 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
configReads 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.
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
+no arguments
+--get <GET>: Reads a config key
--set <SET>: Sets a config key to a string
--set-int <SET_INT>: Sets a config key to an integer
--set-bool <SET_BOOL>: Sets a config key to a bool
--unset <UNSET>: Remove a config key
--show-path: Print the path to the config
--format <FORMAT>: Request parseable output format rather than lines
[possible values: json]
+-h, --help: Print help (see a summary with '-h')
fetchFetches 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.
+Fetch a specific version of Python:
+$ rye fetch 3.8.13
+Downloading cpython@3.8.13
+Checking checksum
+Unpacking
+Downloaded cpython@3.8.13
+To fetch the pinned version of Python you can leave out the argument:
+$ rye fetch
+Downloading cpython@3.8.17
+Checking checksum
+Unpacking
+Downloaded cpython@3.8.17
+To fetch a version of Python into a specific location rather than rye's +interpreter cache:
+$ rye fetch cpython@3.9.1 --target-path=my-interpreter
+[VERSION]: The version of Python to fetch.
If no version is provided, the requested version will be fetched.
+-f, --force: Fetch the Python toolchain even if it is already installed.
--target-path <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')
fmtnew 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.
+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
+[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.
-a, --all: Format all packages in the workspace
-p, --package <PACKAGE>: Format a specific package
--pyproject <PYPROJECT_TOML>: 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')
This is a list of all the commands that rye provides:
+The toplevel rye command accepts the following options:
--env-file <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.initThis 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.
+$ rye init
+success: Initialized project in /Users/john/Development/my-project.
+ Run `rye sync` to get started
+[PATH]: Where to place the project (defaults to current path)--min-py <MIN_PY>: Minimal Python version supported by this project
-p, --py <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 <BUILD_SYSTEM>: Which build system should be used(defaults to hatchling)?
[possible values: hatchling, setuptools, flit, pdm, maturin]
--license <LICENSE>: Which license should be used? SPDX identifier
--name <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_FILE>: Requirements files to initialize pyproject.toml with
--dev-requirements <DEV_REQUIREMENTS_FILE>: 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')
installInstalls 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.
+$ 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 |
+ || ||
+<REQUIREMENT>...: The package to install as PEP 508 requirement string.--git <GIT>: Install the given package from this git repository
--url <URL>: Install the given package from this URL
--path <PATH>: Install the given package from this local path
--absolute: Force non interpolated absolute paths
--tag <TAG>: Install a specific tag
--rev <REV>: Update to a specific git rev
--branch <BRANCH>: Update to a specific git branch
--features <FEATURES>: Adds a dependency with a specific feature
--include-dep <INCLUDE_DEP>: Include scripts from a given dependency
--extra-requirement <EXTRA_REQUIREMENT>: Additional dependencies to install that are not declared by the main package
-p, --python <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')
lintnew 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.
+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
+[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.
-a, --all: Lint all packages in the workspace
-p, --package <PACKAGE>: Format a specific package
--pyproject <PYPROJECT_TOML>: 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')
listnew in 0.24.0
+Prints a list of installed dependencies.
+$ 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
+no arguments
+--pyproject: Use this pyproject.toml file
-h, --help: Print help (see a summary with '-h')
lockUpdates the lockfiles without installing dependencies. Usually one would use
+the sync command instead which both locks and installs dependencies.
For more information see Syncing and Locking.
+$ rye lock
+Generating production lockfile: /Users/username/my-project/requirements.lock
+Generating dev lockfile: /Users/username/my-project/requirements-dev.lock
+Done!
+no arguments
+--update <UPDATE>: Update a specific package
--update-all: Update all packages to the latest
--pre: Update to pre-release versions
--features <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 <PYPROJECT_TOML>: 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')
make-reqBuilds 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 but rather than adding the
+requirements into the requirements file it just spits out a formatted PEP 508 requirement
+string on stdout.
$ rye make-req flask --git https://github.com/pallets/flask --rev 4df377cfbf
+flask @ git+https://github.com/pallets/flask@4df377cfbf
+[REQUIREMENTS]... The package to add as PEP 508 requirement string. e.g. 'flask==2.2.3'--git <GIT>: Install the given package from this git repository
--url <URL>: Install the given package from this URL
--path <PATH>: Install the given package from this local path
--absolute: Force non interpolated absolute paths
--tag <TAG>: Install a specific tag
--rev <REV>: Update to a specific git rev
--branch <BRANCH>: Update to a specific git branch
--features <FEATURES>: Adds a dependency with a specific feature
-h, --help: Print help (see a summary with '-h')
pinPins 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.
+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
+<VERSION>: The version of Python to pin
This can be a short version (3.9) or a full one (cpython@3.9.18).
--relaxed: Issue a relaxed pin
--no-update-requires-python: Prevent updating requires-python in the pyproject.toml
--pyproject <PYPROJECT_TOML>: Use this pyproject.toml file
-h, --help: Print help (see a summary with '-h')
publishPublish packages to a package repository. This publishes the packages which are +produced by the build command.
+For more information see Building and Publishing.
+Build and publish:
+$ rye build
+$ rye publish
+Publish a specific artifact:
+$ rye publish dist/example-0.1.0.tar.gz
+[DIST]...: The distribution files to upload to the repository (defaults to <workspace-root>/dist/*)-r, --repository <REPOSITORY>: The repository to publish to [default: pypi]
--repository-url <REPOSITORY_URL>: The repository url to publish to
-u, --username <USERNAME>: The username to authenticate to the repository with
--token <TOKEN>: An access token used for the upload
--sign: Sign files to upload using GPG
-i, --identity <IDENTITY>: GPG identity used to sign files
--cert <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')
removeRemoves 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 command or pass
+--sync.
new in 0.26.0
+Added support for auto-sync and the --sync / --no-sync flags.
$ rye remove flask
+Removed flask>=3.0.1
+<REQUIREMENTS>...: The packages to remove from the project--dev: Remove this from dev dependencies
--optional <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')
runRuns 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.
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
+[COMMAND]: The name of the command and the arguments to it.-l, --list: List all commands (implied without arguments)
--pyproject: Use this pyproject.toml file
-h, --help: Print help (see a summary with '-h')
completionGenerates a completion script for a shell
+Generate a completion script for zsh and load it:
+$ eval "$(rye self completion -s zsh)"
+no arguments
+-s, --shell <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')
selfCommand to manage Rye itself.
+completion: Generates a completion script for Rye.
update: Performs an update of Rye.
uninstall: Uninstalls Rye again.
uninstallUninstalls 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.
Uninstall rye without asking:
+$ rye self uninstall --yes
+no arguments
+-y, --yes: Do not prompt and uninstall.
-h, --help: Print help (see a summary with '-h')
updatePerforms an update of rye.
+This can install updates from the latest release binaries or trigger a manual +compilation of Rye if Rust is installed.
+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
+no arguments
+--version <VERSION>: Update to a specific version
--tag <TAG>: Update to a specific tag
--rev <REV>: Update to a specific git rev
--branch <BRANCH>: Update to a specific git branch
--force: Force reinstallation
-h, --help: Print help (see a summary with '-h')
showPrints 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.
+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: cpython@3.9.18
+virtual: false
+no arguments
+--installed-deps: Print the currently installed dependencies.
This option is being replaced with rye list
--pyproject: Use this pyproject.toml file
-h, --help: Print help (see a summary with '-h')
syncUpdates the lockfiles and installs the dependencies into the virtualenv.
+For more information see Syncing and Locking.
+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.
no arguments
+-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>: Update a specific package
--update-all: Update all packages to the latest
--pre: Update to pre-release versions
--features <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 <PYPROJECT_TOML>: 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')
testnew 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.
+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%]
+[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.
-a, --all: Test all packages in the workspace
-p, --package <PACKAGE>: Run the test suite of a specific package
--pyproject <PYPROJECT_TOML>: 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')
fetchFetches 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.
+Fetch a specific version of Python:
+$ rye fetch 3.8.13
+Downloading cpython@3.8.13
+Checking checksum
+Unpacking
+Downloaded cpython@3.8.13
+To fetch the pinned version of Python you can leave out the argument:
+$ rye fetch
+Downloading cpython@3.8.17
+Checking checksum
+Unpacking
+Downloaded cpython@3.8.17
+To fetch a version of Python into a specific location rather than rye's +interpreter cache:
+$ rye fetch cpython@3.9.1 --target-path=my-interpreter
+[VERSION]: The version of Python to fetch.
If no version is provided, the requested version will be fetched.
+-f, --force: Fetch the Python toolchain even if it is already installed.
--target-path <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')
toolchainHelper utility to manage Python toolchains. The following subcommands exist:
+ + + + + + + +listList all registered toolchains. It can list the toolchains which are installed as
+well as toolchains which can be downloaded if --include-downloadable is passed.
List installed toolchains:
+$ rye toolchain list
+cpython@3.12.1 (/Users/username/.rye/py/cpython@3.12.1/install/bin/python3)
+cpython@3.11.6 (/Users/username/.rye/py/cpython@3.11.6/install/bin/python3)
+Lists downloadable toolchains:
+$ rye toolchain list --include-downloadable
+cpython@3.12.1 (/Users/mitsuhiko/.rye/py/cpython@3.12.1/install/bin/python3)
+cpython-x86_64@3.12.1 (downloadable)
+cpython@3.11.7 (downloadable)
+...
+no arguments
+--include-downloadable: Also include non installed, but downloadable toolchains
--format <FORMAT>: Request parseable output format [possible values: json]
-h, --help: Print help
registerRegister 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 command.
$ rye toolchain register /opt/homebrew/Cellar/python@3.10/3.10.6_1/bin/python3.10
+Registered /opt/homebrew/Cellar/python@3.10/3.10.6_1/bin/python3.10 as cpython@3.10.6
+<PATH>: Path to the python binary that should be registered-n, --name <NAME>: Name of the toolchain. If not provided a name is auto detected.
-h, --help: Print help (see a summary with '-h')
removeRemoves or uninstalls a toolchain.
+$ rye toolchain remove 3.9.5
+Removed installed toolchain cpython@3.9.5
+<VERSION> The version of Python to remove.-f, --force: Force removal even if the toolchain is in use-h, --help: Print help (see a summary with '-h')installInstalls 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.
+$ 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 |
+ || ||
+<REQUIREMENT>...: The package to install as PEP 508 requirement string.--git <GIT>: Install the given package from this git repository
--url <URL>: Install the given package from this URL
--path <PATH>: Install the given package from this local path
--absolute: Force non interpolated absolute paths
--tag <TAG>: Install a specific tag
--rev <REV>: Update to a specific git rev
--branch <BRANCH>: Update to a specific git branch
--features <FEATURES>: Adds a dependency with a specific feature
--include-dep <INCLUDE_DEP>: Include scripts from a given dependency
--extra-requirement <EXTRA_REQUIREMENT>: Additional dependencies to install that are not declared by the main package
-p, --python <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')
listLists all already installed global tools.
+For more information see Tools.
+List installed tools:
+$ rye tools list
+pycowsay
+List installed tools with version:
+$ rye tools list --include-version
+pycowsay 0.0.0.2 (cpython@3.12.1)
+no arguments
+-s, --include-scripts: Show all the scripts installed by the toolschanged in 0.26.0
+Renamed from -i, --include-scripts to -s, --include-scripts.
-v, --include-version: Show the version of toolschanged in 0.26.0
+Renamed from -v, --version-show to -v, --include-version.
-h, --help: Print helpuninstallUninstalls an already installed global tool. This command has two names
+to rye tools uninstall and rye uninstall.
For more information see Tools.
+$ rye tools uninstall pycowsay
+Uninstalled pycowsay
+<NAME>: The package to uninstall.-v, --verbose: Enables verbose diagnostics
-q, --quiet: Turns off all output
-h, --help: Print help (see a summary with '-h')
uninstallUninstalls an already installed global tool. This command has two names
+to rye tools uninstall and rye uninstall.
For more information see Tools.
+$ rye tools uninstall pycowsay
+Uninstalled pycowsay
+<NAME>: The package to uninstall.-v, --verbose: Enables verbose diagnostics
-q, --quiet: Turns off all output
-h, --help: Print help (see a summary with '-h')
versionGet 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.
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
+[VERSION]: the version to set-b, --bump <BUMP>: automatically bump the version in a specific way (major, minor or patch)
-h, --help: Print help (see a summary with '-h')
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.
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.
The .rye home folder contains both user configuration as well as Rye-managed state such
+as installed toolchains. The following files and folders are placed within the
+.rye folder. Note that not all are always there.
config.tomlThis is a configuration file that influences how Rye operates. Today very little configuration +is available there. For the available config keys see Config File.
+selfWhile Rye is written in Rust, it uses a lot of Python tools internally. These are maintained in +an internal virtualenv stored in this location.
+pyIn this folder Rye stores the different toolchains. Normally those are folders +containing downloaded Python distributions, but they can also be symlinks or special reference +files.
+shimsThis folder contains shim binaries. These binaries are for instance the python executable
+which automatically proxies to the current virtualenv or globally installed tools.
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 = "cpython@3.11.1"
+
+# 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 <email>".
+author = "Full Name <email@address.invalid>"
+
+# 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
+
+# When set to `true`, Rye will use `uv` for package resolution and installation.
+# Set to `false` to fall back to the `pip-tools` resolver.
+# Learn more about uv here: https://github.com/astral-sh/uv
+use-uv = true
+
+# 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/"
+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.
For the project-specific pyproject.toml config see pyproject.toml.
Dependencies are declared in pyproject.toml however adding them can be
+simplified with the rye add command. In the most simple invocation it adds a regular
+dependency, but it can be customized.
To add a regular dependency just invoke rye add with the name of the Python package:
rye add Flask
+If you also want to define a version, use a PEP 508 +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.
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
+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 key.
To run tools added this way without enabling the virtualenv use rye run:
rye run black
+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.
+ + + + + + +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.
+This guide requires some familiarity with Docker and Dockerfiles.
+Make sure that your project is set up as a virtual project. + 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.
+pyproject.toml should contain virtual = true under the [tool.rye] section. If it's not there, add it and run rye sync.rye init --virtual instead of rye init.Create a Dockerfile in your project root with the following content:
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
+You can now build your image like this:
+docker build .
+The Dockerfiles in this guide are examples. Some adjustments you might want to make:
CMD python src/main.py) should point to your script.FROM python:slim):.python-version file, e.g. FROM python:3.12.0-slim.-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.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/*
+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:
FROM python:slim
+RUN --mount=source=dist,target=/dist PYTHONDONTWRITEBYTECODE=1 pip install --no-cache-dir /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 apply.
+Rye's lock file standard is the requirements.txt format from pip, 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 PYTHONDONTWRITEBYTECODE=1 env var and --no-cache-dir parameters when invoking Pip both make the image smaller by not writing any temporary files.
+Both Bytecode and Pip caches are speeding things up when running Pip multiple times, but since we are working in a container, we can be pretty sure that we'll never invoke pip again.
This section should cover some commonly asked questions. If you do not find an answer +here, consider reaching out to the community.
+PyTorch requires setting up manual sources as it's not installed via
+PyPI. These sources can be set up in pyproject.toml for a
+simple project or globally in the 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
+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:
+In more modern versions:
+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:
+.rye\py path are non executable.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:
pacman -S libxcrypt-compatdnf install libxcrypt-compatThere 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
+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.
This issue is inherited from python-build-standalone and more information can
+be found in the documentation: References to Build-Time Paths. There is also an open
+Rye issue for it: Issue #621.
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"
+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 in the +Standalone Python Builds documentation for solutions.
+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!
+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
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" 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"]
+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.
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.
+ + + + + + +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 to learn about +how to get Rye onto your system. Once that is done, read the Basics +to learn about how Rye can be used.
+ + + + + + +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.
+Rye is installed per-user and self manages itself. It will install itself into +a folder in your home directory and manage itself there.
+ +To install you can run a curl command which will install the right binary for your +operating system and CPU architecture and install it:
+curl -sSf https://rye.astral.sh/get | bash
+Alternatively if you don't trust this approach, you can download the latest release +binary. On first run it will install itself.
+gunzip rye-x86_64-linux.gz
+chmod +x ./rye-x86_64-linux
+./rye-x86_64-linux
+To install you can run a curl command which will install the right binary for your +operating system and CPU architecture and install it:
+curl -sSf https://rye.astral.sh/get | bash
+Alternatively if you don't trust this approach, you can download the latest release +binary. On first run it will install itself.
+gunzip rye-aarch64-macos.gz
+chmod +x ./rye-aarch64-macos
+./rye-aarch64-macos
+To install Rye on windows download the latest release and run the binary. Upon +first run it will install itself. Please note that it's strongly recommended +to have "Developer Mode" activated when using Rye and before starting the +installation. Learn more.
+Note
+Rye does not yet use signed binaries which means that you will need to allow +the execution of the downloaded executable. If there is no obvious way to do so, click +on "More info" on the error message that shows up and then on "Run anyway".
+Additionally sometimes a Trojan warning about "Bearfoos" is shown. This is a false +positive. For more information see the discussion Windows Bearfoos +virus associated with rye.
+You need to have Rust and Cargo installed. If you don't have, you can use +rustup to get them onto your machine.
+Afterwards you can install Rye via cargo:
cargo install --git https://github.com/astral-sh/rye rye
+Rye will automatically download suitable Python toolchains as needed. For more +information about this read about toolchains. To install +a specific version download a binary directly +from GitHub.
+On some platforms there is some limited support for customizing the installation +experience. This for instance can be necessary on certain Linux environments such +as Alpine where the Rye provided Python interpreter is not supported.
+
+The install script that is piped to bash can be customized with some environment
+variables:
RYE_VERSIONDefaults to latest. Can be set to an explicit version to install a specific one.
RYE_INSTALL_OPTIONCan optionally be set to "--yes" to skip all prompts.
RYE_TOOLCHAINOptionally 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_VERSIONFor 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_VERSIONDefaults to latest. Can be set to an explicit version to install a specific one.
RYE_INSTALL_OPTIONCan optionally be set to "--yes" to skip all prompts.
RYE_TOOLCHAINOptionally 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_VERSIONFor 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_TOOLCHAINOptionally 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_VERSIONFor 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
+Once rye is installed you need to add the shims folder into your PATH.
+This folder is a folder that contains "shims" which are executables that
+Rye manages for you as well as the rye executable itself. For instance any
+Python installation managed by Rye will be available via a shim placed there.
On macOS or Linux you can accomplish this by adding it to your .profile file
+or similar. This step is technically optional but required if you want to be able to
+just type python or rye into the shell to pick up the current virtualenv's Python
+interpreter. The installer will offer to do this for you automatically. If you
+opt-out, or you run a custom shell you will need to do this manually.
Rye ships an env file which should be sourced to update PATH automatically.
echo 'source "$HOME/.rye/env"' >> ~/.profile
+In some setups .profile is not sourced, in which case you can add it to your
+.bashrc:
echo 'source "$HOME/.rye/env"' >> ~/.bashrc
+Rye ships an env file which should be sourced to update PATH automatically.
echo 'source "$HOME/.rye/env"' >> ~/.zprofile
+In some setups .zprofile is not sourced, in which case you can add it to your
+.zshrc:
echo 'source "$HOME/.rye/env"' >> ~/.zshrc
+Since fish does not support env files, you need to add
+the shims directly. This can be accomplished by running this
+command once:
set -Ua fish_user_paths "$HOME/.rye/shims"
+Since nushell does not support env files, you need to add
+the shims directly. This can be accomplished by adding this to your
+env.nu file:
$env.PATH = ($env.PATH | split row (char esep) | append "~/.rye/shims")
+Rye ships an env file which should be sourced to update PATH automatically.
echo '. "$HOME/.rye/env"' >> ~/.profile
+The windows installer normally will automatically register the rye path in the
+PATH environment variable. If this does not work you will need to manually
+perform the following steps:
sysdm.cpl and hit Enter.Path variable.%USERPROFILE%\.rye\shims and hit Enter.Note that you might need to restart your login session for this to take effect.
+There is a quite a bit to shims and their behavior. Make sure to read up on shims +to learn more.
+Rye supports generating completion scripts for Bash, Zsh, Fish, Powershell and Nushell. Here are some common locations for each shell:
+mkdir -p ~/.local/share/bash-completion/completions
+rye self completion > ~/.local/share/bash-completion/completions/rye.bash
+# Make sure ~/.zfunc is added to fpath, before compinit.
+rye self completion -s zsh > ~/.zfunc/_rye
+Oh-My-Zsh:
+mkdir $ZSH_CUSTOM/plugins/rye
+rye self completion -s zsh > $ZSH_CUSTOM/plugins/rye/_rye
+Then make sure rye plugin is enabled in ~/.zshrc
+rye self completion -s fish > ~/.config/fish/completions/rye.fish
+# Create a directory to store completion scripts
+mkdir $PROFILE\..\Completions
+echo @'
+Get-ChildItem "$PROFILE\..\Completions\" | ForEach-Object {
+ . $_.FullName
+}
+'@ | Out-File -Append -Encoding utf8 $PROFILE
+# Generate script
+Set-ExecutionPolicy Unrestricted -Scope CurrentUser
+rye self completion -s powershell | Out-File -Encoding utf8 $PROFILE\..\Completions\rye_completion.ps1
+rye self completion -s nushell | save --append $nu.env-path
+To update rye to the latest version you can use rye itself:
rye self update
+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.
Rye when launched will normally perform an auto installation. This can be annoying
+in certain development situations. This can be prevented by exporting the
+RYE_NO_AUTO_INSTALL environment variable. It needs to be set to 1 to disable
+the feature.
export RYE_NO_AUTO_INSTALL=1
+export RYE_NO_AUTO_INSTALL=1
+set RYE_NO_AUTO_INSTALL=1
+Rye currently uses build to build the package and uses twine to publish it.
+By default, rye will build both the sdist and wheel targets in the dist directory. The command for this is called 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
+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
+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/
+You can optionally set the --yes flag to skip the confirmation prompt. This can be useful for CI/CD pipelines.
rye publish --token <your_token> --yes
+Rye will store your repository info in $HOME/.rye/credentials for future use.
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.
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.dependenciesThis 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.scriptsThis 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'
+my-hello-script that will call the main function of the
+hello module.
+Scripts can be installed using rye sync and run using rye run:
$ rye sync
+$ rye run my-hello-script
+Hello from hello!
+tool.rye.dev-dependenciesThis 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-dependenciesThis 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.universalnew 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-hashesnew 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-sourcesnew 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.managednew 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.virtualnew 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.
+tool.rye.sourcesThis 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.
+tool.rye.scriptsThis 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:
+cmdThe 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"] }
+envThis 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-filenew 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" }
+chainThis 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"
+callThis 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:
<module_name>: equivalent to python -m <module_name><module_name>:<function_name>: runs <function_name> from <module_name> and exits with the return value<module_name>:<function_name>(<args>): passes specific arguments to the functionExtra 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.workspaceWhen a table with that key is stored, then a project is declared to be a
+workspace 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.
+ + + + + + +Rye recommends using maturin to develop Rust Python
+extension modules. This process is largely automated and new projects can be created
+with rye init.
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
+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
+Note that maturin develop requires pip to be installed into the virtualenv. Before
+you can use it you need to add it:
rye add --dev pip
+rye sync
+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
+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.
+new in 0.9.0
+To enable global shims, you need to enable the global-python flag in
+the config.toml 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.
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.
+An index can be added to a project or workspace (via pyproject.toml) or into the
+global config. 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.
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.
+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.
[[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.
The two sources types (index vs find-links) are determined by the underlying pip
+infrastructure:
indexThis is a PEP 503 type index as provided
+by tools such as PyPI or devpi. It corresponds to
+the arguments --index-url or --extra-index-url in pip.
Note: see the uv documentation
+for more on the use of multiple indexes.
find-linksThis 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.
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.
[[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/"
+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
+Rye supports two systems to manage dependencies:
+uv and
+pip-tools. It currently defaults to
+uv as it offers significantly better performance, but will offer you the
+option to use pip-tools instead.
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.
When locking, some options can be provided to change the locking behavior. These flags are
+also all available on rye sync.
--update / --update-allUpdates 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-featuresPython 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, 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
+--preBy 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-sourcesnew in 0.18.0
+By default (unless the tool.rye.lock-with-sources config key is set to true in the
+pyproject.toml) lock files are not generated with source references. This means that
+if custom sources are used the lock file cannot be installed via pip unless also
+--find-links and other parameters are manually passed. This can be particularly useful
+when the lock file is used for docker image builds.
When this flag is passed then the lock file is generated with references to --index-url,
+--extra-index-url or --find-links.
rye lock --with-sources
+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-lockTo prevent the lock step from automatically running, pass --no-lock.
rye sync --no-lock
+--no-devOnly sync based on the production lockfile (requirements.lock) instead of the development
+lockfile (requirements-dev.lock).
rye sync --no-dev
+Lockfiles depend on the platform they were generated on. This is a known limitation +in pip-tools.
+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.
+ + + + + + +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 +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.
+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. Additionally, the Python +Standalone Builds have a Behavior Quirks +page.
+Portable CPython builds are downloaded from GitHub +(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.
+When you pin a Python version to cpython@major.minor.patch (or just
+major.minor.patch) then Rye will automatically download the right version
+for you whenever it is needed. If a custom toolchain has already been registered with that name and
+version, that this is used instead.
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:
+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 cpython@3.11.4
+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 cpython@3.11, 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 cpython@3.11
+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.
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 cpython@3.11 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 cpython-x86_64@3.11
+Note that such custom pins are not reflected in pyproject.toml but only .python-version.
To see which toolchains are installed, rye toolchain list prints a list:
rye toolchain list
+cpython@3.11.1 (C:\Users\armin\.rye\py\cpython@3.11.1\install\python.exe)
+pypy@3.9.16 (C:\Users\armin\.rye\py\pypy@3.9.16\python.exe)
+To see which toolchains can be installed, additionally pass the --include-downloadable:
rye toolchain list --include-downloadable
+Generally Rye automatically downloads toolchains, but they can be explicitly fetched
+with rye toolchain fetch (also aliased to rye fetch):
rye toolchain fetch cpython@3.8.5
+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:
+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 cpython@3.8.5 --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.
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
+To remove an already fetched toolchain run rye toolchain remove. Note that this
+also works for linked toolchains:
rye toolchain remove cpython@3.8.5
+Warning
+Removing an actively used toolchain will render the virtualenvs that refer to use broken.
+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 cpython@3.8.5/bin/python3 there you will instead have an extra install folder
+(cpython@3.8.5/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
+PyPy is supported as alternative Python distribution.
+Like the portable CPython builds it's downloaded automatically. The name for
+PyPy distributions is pypy.
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.
+PyPy builds are downloaded from +downloads.python.org.
+When you pin a Python version to pypy@major.minor.patch then Rye will
+automatically download the right version for you whenever it is needed. If a
+custom toolchain 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 pypy@3.9.16 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.
Rye supports global tool installations. This for instance allows you to install
+tools like black or ruff globally.
Use the rye tools install (aliased to rye
+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.
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
+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
+To uninstall a tool again, use rye tools uninstall (aliased to rye uninstall):
rye uninstall black
+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.
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.
+Virtual projects can not have optional dependencies. These even if declared are not +installed.
+If a workspace does not have a toplevel package it's +recommended that it's declared as virtual.
+ + + + + + +Workspaces are a feature that allows you to work with multiple packages that
+have dependencies to each other. A workspace is declared by setting the
+tool.rye.workspace key a pyproject.toml. Afterwards all projects within
+that workspace share a singular virtualenv.
A workspace is declared by the "toplevel" pyproject.toml. At the very least
+the key tool.rye.workspace needs to be added. It's recommended that a glob
+pattern is also set 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 in 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.
+In a workspace it does not matter which project you are working with, the entire +workspace is synchronized at all times. This has some untypical 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
+
+ Rye is a comprehensive project and package management solution for Python.
+Born from its creator's 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.
A hassle-free experience for Python developers at every level.
+ + + +Installation Instructions
+ +To install you can run a curl command which will install the right binary for your +operating system and CPU architecture and install it:
+curl -sSf https://rye.astral.sh/get | bash
+Alternatively if you don't trust this approach, you can download the latest release +binary. On first run it will install itself.
+gunzip rye-x86_64-linux.gz
+chmod +x ./rye-x86_64-linux
+./rye-x86_64-linux
+To install you can run a curl command which will install the right binary for your +operating system and CPU architecture and install it:
+curl -sSf https://rye.astral.sh/get | bash
+Alternatively if you don't trust this approach, you can download the latest release +binary. On first run it will install itself.
+gunzip rye-aarch64-macos.gz
+chmod +x ./rye-aarch64-macos
+./rye-aarch64-macos
+To install Rye on windows download the latest release and run the binary. Upon +first run it will install itself. Please note that it's strongly recommended +to have "Developer Mode" activated when using Rye and before starting the +installation. Learn more.
+Note
+Rye does not yet use signed binaries which means that you will need to allow +the execution of the downloaded executable. If there is no obvious way to do so, click +on "More info" on the error message that shows up and then on "Run anyway".
+Additionally sometimes a Trojan warning about "Bearfoos" is shown. This is a false +positive. For more information see the discussion Windows Bearfoos +virus associated with rye.
+You need to have Rust and Cargo installed. If you don't have, you can use +rustup to get them onto your machine.
+Afterwards you can install Rye via cargo:
cargo install --git https://github.com/astral-sh/rye rye
+For the next steps or ways to customize the installation, head over to the detailed +installation guide.
+Rye was built to solve my 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 it's 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 and
+ pip-tools behind the scenes.
No Pip: Rye uses pip, but it does not expose it. It manages dependencies in
+ 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. + 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.
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 were to install something
+ into the virtualenv, it disappears next time you sync. If you symlink rye to
+ ~/.rye/shims/pip you can get access to pip without installing it into the
+ virtualenv. There be dragons.
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.
This describes of what I envision Python packaging and project management could +look like in an ideal world:
+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 libc@0.2, they will all resolve to
+that dependency. However if another need arises for libc@1.0, 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 important-lib@0.2.32 to depend on
+important-lib@1.0 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.
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.
+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:
+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:
+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:
+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:
+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:
+pyproject.toml that declares that a package supports multi-versioningWith 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:
+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:
+.venv in the workspace root)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
+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:
+package-foo does not provide a package_foo moduleSome 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.
+ + + + + + +Rye is a comprehensive project and package management solution for Python. Born from its creator's 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.
A hassle-free experience for Python developers at every level.
Star Discuss Sponsor
Installation Instructions
LinuxmacOSWindowsCompile YourselfTo 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\nAlternatively if you don't trust this approach, you can download the latest release binary. On first run it will install itself.
gunzip rye-x86_64-linux.gz\nchmod +x ./rye-x86_64-linux\n./rye-x86_64-linux\nTo 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\nAlternatively if you don't trust this approach, you can download the latest release binary. On first run it will install itself.
gunzip rye-aarch64-macos.gz\nchmod +x ./rye-aarch64-macos\n./rye-aarch64-macos\nTo install Rye on windows download the latest release and run the binary. Upon first run it will install itself. Please note that it's strongly recommended to have \"Developer Mode\" activated when using Rye and before starting the installation. Learn more.
Note
Rye does not yet use signed binaries which means that you will need to allow the execution of the downloaded executable. If there is no obvious way to do so, click on \"More info\" on the error message that shows up and then on \"Run anyway\".
Additionally sometimes a Trojan warning about \"Bearfoos\" is shown. This is a false positive. For more information see the discussion Windows Bearfoos virus associated with rye.
You need to have Rust and Cargo installed. If you don't have, you can use rustup to get them onto your machine.
Afterwards you can install Rye via cargo:
cargo install --git https://github.com/astral-sh/rye rye\nFor the next steps or ways to customize the installation, head over to the detailed installation guide.
"},{"location":"changelog/","title":"Changelog","text":"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 file in the repository.
"},{"location":"changelog/#0390","title":"0.39.0","text":"Released on 2024-08-20.
add.md by @mikkelam in https://github.com/astral-sh/rye/pull/1322v0.3.0 by @github-actions in https://github.com/astral-sh/rye/pull/1332Released on 2024-08-01.
rye add and rye remove to create proper tool.rye section for --dev and --exclude flags by @flyaroundme in https://github.com/astral-sh/rye/pull/1256uninstall_cmd on Windows by @250h in https://github.com/astral-sh/rye/pull/1153--index-url before --extra-index-url by @charliermarsh in https://github.com/astral-sh/rye/pull/1278rye.exe by @charliermarsh in https://github.com/astral-sh/rye/pull/1286v0.2.33 by @github-actions in https://github.com/astral-sh/rye/pull/1303v24.2.0 by @charliermarsh in https://github.com/astral-sh/rye/pull/1304Released on 2024-07-20.
-d for rye remove --dev by @nikhilweee in https://github.com/astral-sh/rye/pull/1239v0.2.27 by @github-actions in https://github.com/astral-sh/rye/pull/12323.12.4 by @github-actions in https://github.com/astral-sh/rye/pull/1230.python-version in Rye builds by @charliermarsh in https://github.com/astral-sh/rye/pull/1250v0.5.4 by @charliermarsh in https://github.com/astral-sh/rye/pull/1251Released on 2024-07-07.
Released on 2024-06-24.
--pre when auto-syncing by @charliermarsh in https://github.com/astral-sh/rye/pull/1107rye-up.com to rye.astral.sh by @charliermarsh in https://github.com/astral-sh/rye/pull/1113powershell) by @charliermarsh in https://github.com/astral-sh/rye/pull/1125config.toml error messages by @zys864 in https://github.com/astral-sh/rye/pull/1155Released on 2024-05-20.
.com) binaries on Windows by @mataha in https://github.com/astral-sh/rye/pull/1091use-uv = true in no-prompt mode by @charliermarsh in https://github.com/astral-sh/rye/pull/1098Released on 2024-04-24.
Ensure files created by rye init, such as pyproject.toml and initial python files end with a newline. #979
Add --refresh argument on -f. #994
Preserve trailing newline in templates. #979
Update uv to 0.1.37. #980
Allow comments in .python-version. #1038
Update Python releases to include 3.12.3 et al. #1022
Released on 2024-03-29
Update uv to 0.1.26. #924
Always create .gitignore file in rye init. #919
Prevent rye fetch --force from removing a target directory that is not a Python installation. #921
rye list always prints the currently installed packages even this project is not managed by Rye. #940
Fix error on using -v or -q with rye fmt or rye lint. #959
Fix rye fetch detection of registered toolchain. #931
Ignore build-system configuration for virtual projects. #929
Released on 2024-03-22
Update uv to 0.1.23. #916
Allow rye publish working outside of project. #910
rye test --quiet no longer implies --no-capture. #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/cpython@3.11.1/install/bin/python3 it will now reside at ~/.rye/py/cpython@3.11.1/bin/python3. #917
Installer now recommends uv over pip-tools. #918
Released on 2024-03-19
Update uv to 0.1.21. #884, #890, #904
Fix incorrect flag passing of rye test -q and -v. #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
Fix rye add m --path ./m causing a panic on windows. #897
Released on 2024-03-11
Updated to uv 0.1.17. #850, #867
Trap panics and silence bad pipe errors. #862
Updating rye will now also ensure that the self-venv is updated. Previously this was deferred until the next sync. #863
The self update command now accepts --branch. #864
Fixed an issue that caused pip-tools to not update. #865
Updates build and certifi. #866
Released on 2024-03-07
--skip-existing is now available with Rye's publish command. #831
Bumped uv to 0.1.15. #760, #820, #837
Bumped ruff to 0.3.0. #821
The init command now generates a script with the name of the project rather than hello. #801
Retain markers when adding dependencies with features when uv is used. #807
Fixed a bug that caused repeated syncs not to recall all previous options. #830
Report self-python version in --version. #843
Fixes a bug where rye config would not create the RYE_HOME folder if needed. #844
rye add now retains version and URL for the requirements when uv is used. #846
Added a rye test command which invokes pytest. #847
Released on 2024-02-26
rye now uses uv to bootstrap its internal packages and tools. #754
rye no longer fails if an incorrect VIRTUAL_ENV environment variable is exported. #766
Added latest Python builds. #771
When uv is used the prompt is now set to the project name. #773
Allow rye fetch --force to force re-fetch a downloaded toolchain. #778
Fixed a panic when adding a package to a virtual project. #783
Bumped uv to 0.1.11. #790
Released on 2024-02-23
init now supports --script and --lib to generate a script or library project. #738
Fixed rye config --show-path abort with an error. #706
Bumped uv to 0.1.9. #719, #740, #746
Bumped ruff to 0.2.2. #700
Prevent rye toolchain remove from removing the currently active toolchain. #693
Sync latest PyPy releases. #683
Fixes an issue where when uv is enabled, add did not honor custom sources. #720
When uv is enabled, rye will now automatically sync on add and remove. #677
Rename rye tools list flags: -i, --include-scripts to -s, --include-scripts and -v, --version-show to -v, --include-version. #722
Released on 2024-02-19
Improved the error message if config is invoked without arguments. #660
Bump uv to 0.1.5. #665, #675, #698
When uv is enabled, rye add now uses uv instead of unearth internally. #667
The installer now has slightly better wording for what the shims are doing. #669
uv can now also be enabled on windows. #675
Removed the unsupported and un-used arch parameter from fetch. #681
Fixed the -q parameter not working for the init command. #686
rye tools list shows broken tools if the toolchain was removed. #692
Configure the ruff cache directory to be located within the workspace root. #689
Use default toolchain to install tools. #666
rye --version now shows if uv is enabled. #699
Released on 2024-02-15
Added new rye list command and deprecated rye show --installed-deps which it replaces. #656
Added experimental support for uv. #657
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
Fixed a bug that caused warnings about unsupported operations to be shown on Linux. #634
The venv sync marker is now only updated when a new virtualenv is created. #638
Lockfiles now contain annotations. #643
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
Fixed a bug where pip-tools sometimes did not get initialized. #596
Rye now prefers installed toolchains over newer latest toolchains unless a precise pin is used. #598
Removed the non functional shell command. #602
Upgraded internal unearth dependency which resolved an issue where rye add tensorflow would not work. #614
The installer now supports RYE_TOOLCHAIN_VERSION. #606
rye init will no longer create packages with leading digits. #616
Rye now statically links vcruntime on Windows which no longer requires the vs redist to be installed. #622
rye show now prints out which sources are configured for a project. #631
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
The rye installer now prompts for the default toolchain version if global shims are enabled. #576
The internal Python version was bumped to 3.12. #576
The installer now can automatically add Rye to PATH on most UNIX environments. #580
Released on 2024-02-01
Improved the error message when an update could not be performed because files are in use. #550
Rye now supports virtual projects. These are themselves not installed into the virtualenv but their dependencies are. #551
Update the Python internals (python external dependencies) to new versions. #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
Added rye fmt and rye lint commands to format and lint with the help of Ruff. #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
Upon installation Rye now prompts if global shims should be enabled. #566
Add a warning about bugs to the shell command until the behavior has been fixed. #567
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
Fixed an issue where rye init would pin a much too specific version in the .python-version file that is generated. #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
Fixed a regression in 0.18 that caused the add command to fail. #547
Released on 2024-01-20
Incorporate new Python builds. #535
Disable revocation checks on windows to support corporate MITM proxies. #537
Detect when a virtualenv relocates and automatically re-create it on sync. #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
When using global python shims, the .python-version file is now correctly picked up in all cases. #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
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
Released on 2024-01-15
Fixed default generated script reference. #527
Correctly fall back to home folder if HOME is unset. #533
Released on 2023-12-17
By default a script with the name of the project is now also configured. #519
Rye now configures hatchling better in rye init so that it works with hatchling 1.19 and later. #521
Rye now detects the dummy Python shim that starts the windows store and refuses to consider it. #486
Released on 2023-10-04
Released on 2023-10-03
Released on 2023-10-03
Released on 2023-10-01
Add support for fetching alternative CPU architectures. #447
The order of git submodule initialization was changed. This improves the automatic author detection when includeIf is used. #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
The installer now detects fish and will spit out additional instructions for configuring the shell.
Fix the wrong behavior when bump version. #454
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.
Released on 2023-08-27
Improve handling of the pth files for TCL on pypy. #409
The rye tools list command now accepts -v to also print out the versions of the installed tools. #396
Fixed parsing of versions by rye version. #397
Improved the help message for rye init. #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
Fixed an issue where the author email was incorrectly detected. #382
The prompt of new virtualenvs is now set to the project name. #383
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
When importing with rye init and no src folder exists, it will not be created. #375
Added support for shell command on Windows. #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
The version command can show dynamic versions now. #355
rye add now properly checks some incompatible argument combinations. #347
There is now more toolchain validation. This better supports cases where rye was interrupted during sync. #351
Released on 2023-07-07
Fixed a bug with rye init not operating correctly due to a argument conflict. #346
Scripts now support a PDM style call script type. #345
The init command is now capable of importing existing projects. #265
Fixed the global shim behavior on Windows. #344
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
rye add now accepts --pin to let one override the type of pin to use. #341
Added rye config to read and manipulate the config.toml file. #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
Renamed the config key default.dependency_operator to default.dependency-operator and behavior.force_rye_managed to behavior.force-rye-managed. #338
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
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
rye install now lets you install dependencies into the tool's virtualenv during installation that are undeclared via the new --extra-requirement option. #326
Improved handling of relative path installations by setting PROJECT_ROOT the same way as PDM does. #321
Workspaces will now never discover pyproject.toml files in any dot directories. (Name starting with .) #329
Fixed rye build not working correctly on Windows. #327
Released on 2023-06-12
rye sync and rye lock now accept --pyproject. #296
Added JSON output to rye toolchain list by adding --format=json. #306
rye version can bump version by --bump option now. #298
Fixed members not handled correctly in workspaces. #300
Add --clean for build command. #297
Fixed an issue where pip was not invoked from the right working directory causing issues for workspace installations. #292
rye init now accepts --private to set the Private :: Do Not Upload classifier that prevents uploads to PyPI. #291
Released on 2023-06-03
Add version subcommand for rye. #285
Fixed rye pin pinning the wrong version. #288
Calling rye init on the root directory no longer fails. #274
rye run, show, pin, shell and build now take a --pyproject argument. #232
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
The publish command now supports --yes to disable prompts. #270
When a Python debug build (Py_DEBUG) is registered as custom toolchain, -dbg is automatically appended to the name by default. #269
lto+pgo builds are now preferred for the Python toolchain builds when available. #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
Workspaces will no longer discover pyproject.toml files in virtualenvs or .git folders. #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
Default build-system and license can be specified in global config. #244
Fixed an issue where the init command would not let you create flit based projects. #254
Resolve an error (\"No such file or directory\") shown after updates on Linux machines. #252
The built-in updater now validates checksums of updates when updates have SHA-256 hashes available. #253
init now accepts --no-pin to not create a .python-version file. #247
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
Virtualenvs on Unix are now created with a hack to pre-configure TCL and TKinter. #233
Fix invalid version error when using rye init with custom toolchain. #234
Failed tool installations now properly clean up. #225
Correctly swap the rye executable on windows when performing an update to a git version via self update.
Released on 2023-05-27
Support retrieving username and repository-url from credentials if not provided for the publish command. #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
It's now possible to configure http and https proxies. #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
Add --username parameter for rye publish. #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
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
Support auto fix requires-python when there is a conflict. #160
Added support for custom indexes. #199
rye add no longer complains when a local version information is in the version. #199
Released on 2023-05-22
Fixed dev-dependencies not being installed when using workspace. #170
init no longer creates invalid flit config. #195
Support direct references when adding a package. #158
Fixed a bug with uninstall on Unix platforms. #197
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
Fixed an issue on macOS where the installer would die with \"os error 24\" when directly piped to bash. #184
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
Script declarations in pyproject.toml now permit chaining and custom environment variables. #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 pypy@3.9.16 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.
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:
You can also reach out via Twitter or Bluesky.
"},{"location":"community/#badges","title":"Badges","text":"Want to show that you are using Rye? Why not throw a badge into your project's README.md:
[](https://rye.astral.sh)\n... or README.rst:
.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/rye/main/artwork/badge.json\n :target: https://rye.astral.sh\n :alt: Rye\n... or, as HTML:
<a href=\"https://rye.astral.sh\"><img src=\"https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/rye/main/artwork/badge.json\" alt=\"Rye\" style=\"max-width:100%;\"></a>\nRye was built to solve my 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 it's 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 and pip-tools behind the scenes.
No Pip: Rye uses pip, but it does not expose it. It manages dependencies in 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. 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.
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 were to install something into the virtualenv, it disappears next time you sync. If you symlink rye to ~/.rye/shims/pip you can get access to pip without installing it into the virtualenv. There be dragons.
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.
This describes of what I envision Python packaging and project management could look like in an ideal world:
"},{"location":"philosophy/#the-rust-experience","title":"The Rust Experience","text":"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 libc@0.2, they will all resolve to that dependency. However if another need arises for libc@1.0, 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 important-lib@0.2.32 to depend on important-lib@1.0 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.
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.
"},{"location":"philosophy/#bootstrapping-python","title":"Bootstrapping Python","text":"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:
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:
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:
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:
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:
pyproject.toml that declares that a package supports multi-versioningWith 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:
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:
.venv in the workspace root)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
"},{"location":"philosophy/#opinionated-defaults","title":"Opinionated Defaults","text":"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:
package-foo does not provide a package_foo moduleSome 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.
"},{"location":"guide/","title":"Introduction","text":"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 to learn about how to get Rye onto your system. Once that is done, read the Basics to learn about how Rye can be used.
"},{"location":"guide/basics/","title":"Basics","text":"To use Rye you need to have a pyproject.toml based Python project. For this guide you can create one with rye init which will create a new folder with a new project inside:
rye init my-project\ncd my-project\nThe following structure will be created:
.\n\u251c\u2500\u2500 .git\n\u251c\u2500\u2500 .gitignore\n\u251c\u2500\u2500 .python-version\n\u251c\u2500\u2500 README.md\n\u251c\u2500\u2500 pyproject.toml\n\u2514\u2500\u2500 src\n \u2514\u2500\u2500 my_project\n \u2514\u2500\u2500 __init__.py\nGood 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\nOnce 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\nThe 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.
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)\"\nIt will print out the full path to the managed virtualenv.
"},{"location":"guide/basics/#adding-dependencies","title":"Adding Dependencies","text":"Use the add command to add dependencies to your project.
rye add \"flask>=2.0\"\nFollowed 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 first.
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\nUse the remove command to remove a dependency from the project again.
rye remove flask\nTo 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\nrye sync\nrye run black .\nIf 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\n.venv\\Scripts\\activate\nTo deactivate it again run deactivate:
deactivate\nThe 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\nTo generate a project that is aimed to provide an executable script, use rye init --script:
rye init --script my-project\ncd my-project\nThe following structure will be created:
.\n\u251c\u2500\u2500 .git\n\u251c\u2500\u2500 .gitignore\n\u251c\u2500\u2500 .python-version\n\u251c\u2500\u2500 README.md\n\u251c\u2500\u2500 pyproject.toml\n\u2514\u2500\u2500 src\n \u2514\u2500\u2500 my_project\n \u2514\u2500\u2500 __init__.py\n \u2514\u2500\u2500 __main__.py\nThe pyproject.toml will be generated with a [project.scripts] 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\nrye run my-project\nMost 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.
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.
The .rye home folder contains both user configuration as well as Rye-managed state such as installed toolchains. The following files and folders are placed within the .rye folder. Note that not all are always there.
config.toml","text":"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.
"},{"location":"guide/config/#self","title":"self","text":"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.
"},{"location":"guide/config/#py","title":"py","text":"In this folder Rye stores the different toolchains. Normally those are folders containing downloaded Python distributions, but they can also be symlinks or special reference files.
"},{"location":"guide/config/#shims","title":"shims","text":"This folder contains shim binaries. These binaries are for instance the python executable which automatically proxies to the current virtualenv or globally installed tools.
The config file config.toml in the .rye folder today is only used to manage defaults. This is a fully annotated config file:
[default]\n# This is the default value that is written into new pyproject.toml\n# files for the `project.requires-python` key\nrequires-python = \">= 3.8\"\n\n# This is the default toolchain that is used\ntoolchain = \"cpython@3.11.1\"\n\n# This is the default build system that is used\nbuild-system = \"hatchling\"\n\n# This is the default license that is used\nlicense = \"MIT\"\n\n# This sets the default author (overrides the defaults from git). The\n# format here is \"Name <email>\".\nauthor = \"Full Name <email@address.invalid>\"\n\n# The dependency operator to use by default for dependencies. The options are\n# '>=', '~=', and '=='. The default currently is '>='. This affects the behavior\n# of `rye add`.\ndependency-operator = \">=\"\n\n[proxy]\n# the proxy to use for HTTP (overridden by the http_proxy environment variable)\nhttp = \"http://127.0.0.1:4000\"\n# the proxy to use for HTTPS (overridden by the https_proxy environment variable)\nhttps = \"http://127.0.0.1:4000\"\n\n[behavior]\n# When set to `true` the `managed` flag is always assumed to be `true`.\nforce-rye-managed = false\n\n# Enables global shims when set to `true`. This means that the installed\n# `python` shim will resolve to a Rye-managed toolchain even outside of\n# virtual environments.\nglobal-python = false\n\n# When set to `true`, Rye will use `uv` for package resolution and installation.\n# Set to `false` to fall back to the `pip-tools` resolver.\n# Learn more about uv here: https://github.com/astral-sh/uv\nuse-uv = true\n\n# Enable or disable automatic `sync` after `add` and `remove`. This defaults\n# to `true` when uv is enabled and `false` otherwise.\nautosync = true\n\n# Marks the managed .venv in a way that cloud-based synchronization systems\n# like Dropbox and iCloud Files will not upload it. This defaults to `true`\n# as a .venv in cloud storage typically does not make sense. Set this to\n# `false` to disable this behavior.\nvenv-mark-sync-ignore = true\n\n# When set to `true` Rye will fetch certain interpreters with build information.\n# This will increase the space requirements, will put the interpreter into an\n# extra folder called `./install/` and place build artifacts adjacent in `./build`.\nfetch-with-build-info = false\n\n# An array of tables with optional sources. Same format as in pyproject.toml\n[[sources]]\nname = \"default\"\nurl = \"https://pypi.org/simple/\"\nnew 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\nrye config --set-bool behavior.force-rye-managed=true\nrye config --get default.requires-python\nFor more information see config.
For the project-specific pyproject.toml config see pyproject.toml.
Dependencies are declared in pyproject.toml however adding them can be simplified with the rye add command. In the most simple invocation it adds a regular dependency, but it can be customized.
To add a regular dependency just invoke rye add with the name of the Python package:
rye add Flask\nIf you also want to define a version, use a PEP 508 requirement:
rye add \"Flask>=2.0\"\nFor extra/feature dependencies you can either use PEP 508 syntax or use --features:
rye add \"Flask[dotenv]\"\nrye add Flask --features=dotenv\nThese dependencies are stored in project.dependencies.
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\nFor dependencies that should only be installed during development pass --dev
rye add --dev black\nThese dependencies are stored in the non-standard tool.rye.dev-dependencies key.
To run tools added this way without enabling the virtualenv use rye run:
rye run black\nTo add a local or git dependency, you can pass additional parameters like --path or --git:
rye add Flask --git=https://github.com/pallets/flask\nrye add My-Utility --path ./my-utility\nNote 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.
"},{"location":"guide/docker/","title":"Building a Container with Docker","text":"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.
This guide requires some familiarity with Docker and Dockerfiles.
"},{"location":"guide/docker/#container-from-source","title":"Container from Source","text":"Make sure that your project is set up as a virtual project. 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.
pyproject.toml should contain virtual = true under the [tool.rye] section. If it's not there, add it and run rye sync.rye init --virtual instead of rye init.Create a Dockerfile in your project root with the following content:
FROM python:slim\n\nWORKDIR /app\nCOPY requirements.lock ./\nRUN PYTHONDONTWRITEBYTECODE=1 pip install --no-cache-dir -r requirements.lock\n\nCOPY src .\nCMD python main.py\nYou can now build your image like this:
docker build .\nThe Dockerfiles in this guide are examples. Some adjustments you might want to make:
CMD python src/main.py) should point to your script.FROM python:slim):.python-version file, e.g. FROM python:3.12.0-slim.-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.COPY src .. When using Debian-based images (i.e. -slim or no-suffix variants), that could look like this:RUN apt-get update \\\n&& apt-get install -y --no-install-recommends some-dependency another-dependency \\\n&& rm -rf /var/lib/apt/lists/*\nIf 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:
FROM python:slim\nRUN --mount=source=dist,target=/dist PYTHONDONTWRITEBYTECODE=1 pip install --no-cache-dir /dist/*.whl\nCMD python -m my_package\nTo build your docker image, you'll have to first build your wheel, like this:
rye build --wheel --clean\ndocker build . --tag your-image-name\nNote 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 apply.
"},{"location":"guide/docker/#explanations","title":"Explanations","text":"Rye's lock file standard is the requirements.txt format from pip, 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 PYTHONDONTWRITEBYTECODE=1 env var and --no-cache-dir parameters when invoking Pip both make the image smaller by not writing any temporary files. Both Bytecode and Pip caches are speeding things up when running Pip multiple times, but since we are working in a container, we can be pretty sure that we'll never invoke pip again.
This section should cover some commonly asked questions. If you do not find an answer here, consider reaching out to the community.
"},{"location":"guide/faq/#how-do-i-install-pytorch","title":"How Do I Install PyTorch?","text":"PyTorch requires setting up manual sources as it's not installed via PyPI. These sources can be set up in pyproject.toml for a simple project or globally in the config.
Option 1: pyproject.toml
[[tool.rye.sources]]\nname = \"pytorch\"\nurl = \"https://download.pytorch.org/whl/cpu\"\nOption 2: ~/.rye/config.toml
[[sources]]\nname = \"pytorch\"\nurl = \"https://download.pytorch.org/whl/cpu\"\nAfterwards you can add pytorch as you would expect:
rye add torch torchvision torchaudio\nRye 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:
In more modern versions:
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:
.rye\\py path are non executable.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:
pacman -S libxcrypt-compatdnf install libxcrypt-compatThere 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\"\ncurl -sSf https://rye.astral.sh/get | bash\nThe 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.
This issue is inherited from python-build-standalone and more information can be found in the documentation: References to Build-Time Paths. There is also an open Rye issue for it: Issue #621.
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\nimport sys\nos.environ[\"TCL_LIBRARY\"] = sys.base_prefix + \"/lib/tcl8.6\"\nos.environ[\"TK_LIBRARY\"] = sys.base_prefix + \"/lib/tk8.6\"\nThe 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 in the Standalone Python Builds documentation for solutions.
"},{"location":"guide/faq/#can-i-use-rye-alongside-other-python-installations","title":"Can I use Rye Alongside Other Python Installations?","text":"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!
"},{"location":"guide/faq/#muslalpine-support","title":"Musl/Alpine Support","text":"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
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\" 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]\ninclude = [\"src/my_package\", \"tests\"]\nRye 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.
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.
"},{"location":"guide/installation/","title":"Installation","text":"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.
"},{"location":"guide/installation/#installing-rye","title":"Installing Rye","text":"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 YourselfTo 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\nAlternatively if you don't trust this approach, you can download the latest release binary. On first run it will install itself.
gunzip rye-x86_64-linux.gz\nchmod +x ./rye-x86_64-linux\n./rye-x86_64-linux\nTo 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\nAlternatively if you don't trust this approach, you can download the latest release binary. On first run it will install itself.
gunzip rye-aarch64-macos.gz\nchmod +x ./rye-aarch64-macos\n./rye-aarch64-macos\nTo install Rye on windows download the latest release and run the binary. Upon first run it will install itself. Please note that it's strongly recommended to have \"Developer Mode\" activated when using Rye and before starting the installation. Learn more.
Note
Rye does not yet use signed binaries which means that you will need to allow the execution of the downloaded executable. If there is no obvious way to do so, click on \"More info\" on the error message that shows up and then on \"Run anyway\".
Additionally sometimes a Trojan warning about \"Bearfoos\" is shown. This is a false positive. For more information see the discussion Windows Bearfoos virus associated with rye.
You need to have Rust and Cargo installed. If you don't have, you can use rustup to get them onto your machine.
Afterwards you can install Rye via cargo:
cargo install --git https://github.com/astral-sh/rye rye\nRye will automatically download suitable Python toolchains as needed. For more information about this read about toolchains. To install a specific version download a binary directly from GitHub.
"},{"location":"guide/installation/#customized-installation","title":"Customized Installation","text":"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\n 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\nThe 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\nrye-x86_64-windows.exe\nOnce rye is installed you need to add the shims folder into your PATH. This folder is a folder that contains \"shims\" which are executables that Rye manages for you as well as the rye executable itself. For instance any Python installation managed by Rye will be available via a shim placed there.
On macOS or Linux you can accomplish this by adding it to your .profile file or similar. This step is technically optional but required if you want to be able to just type python or rye into the shell to pick up the current virtualenv's Python interpreter. The installer will offer to do this for you automatically. If you opt-out, or you run a custom shell you will need to do this manually.
Rye ships an env file which should be sourced to update PATH automatically.
echo 'source \"$HOME/.rye/env\"' >> ~/.profile\nIn some setups .profile is not sourced, in which case you can add it to your .bashrc:
echo 'source \"$HOME/.rye/env\"' >> ~/.bashrc\nRye ships an env file which should be sourced to update PATH automatically.
echo 'source \"$HOME/.rye/env\"' >> ~/.zprofile\nIn some setups .zprofile is not sourced, in which case you can add it to your .zshrc:
echo 'source \"$HOME/.rye/env\"' >> ~/.zshrc\nSince 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\"\nSince 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\")\nRye ships an env file which should be sourced to update PATH automatically.
echo '. \"$HOME/.rye/env\"' >> ~/.profile\nThe 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:
sysdm.cpl and hit Enter.Path variable.%USERPROFILE%\\.rye\\shims and hit Enter.Note that you might need to restart your login session for this to take effect.
There is a quite a bit to shims and their behavior. Make sure to read up on shims to learn more.
"},{"location":"guide/installation/#shell-completion","title":"Shell Completion","text":"Rye supports generating completion scripts for Bash, Zsh, Fish, Powershell and Nushell. Here are some common locations for each shell:
BashZshFishPowershellNuShellmkdir -p ~/.local/share/bash-completion/completions\nrye self completion > ~/.local/share/bash-completion/completions/rye.bash\n# Make sure ~/.zfunc is added to fpath, before compinit.\nrye self completion -s zsh > ~/.zfunc/_rye\nOh-My-Zsh:
mkdir $ZSH_CUSTOM/plugins/rye\nrye self completion -s zsh > $ZSH_CUSTOM/plugins/rye/_rye\nThen make sure rye plugin is enabled in ~/.zshrc
rye self completion -s fish > ~/.config/fish/completions/rye.fish\n# Create a directory to store completion scripts\nmkdir $PROFILE\\..\\Completions\necho @'\nGet-ChildItem \"$PROFILE\\..\\Completions\\\" | ForEach-Object {\n . $_.FullName\n}\n'@ | Out-File -Append -Encoding utf8 $PROFILE\n# Generate script\nSet-ExecutionPolicy Unrestricted -Scope CurrentUser\nrye self completion -s powershell | Out-File -Encoding utf8 $PROFILE\\..\\Completions\\rye_completion.ps1\nrye self completion -s nushell | save --append $nu.env-path\nTo update rye to the latest version you can use rye itself:
rye self update\nIf you don't want to use Rye any more, you can ask it to uninstall it again:
rye self uninstall\nAdditionally 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.
Rye when launched will normally perform an auto installation. This can be annoying in certain development situations. This can be prevented by exporting the RYE_NO_AUTO_INSTALL environment variable. It needs to be set to 1 to disable the feature.
export RYE_NO_AUTO_INSTALL=1\nexport RYE_NO_AUTO_INSTALL=1\nset RYE_NO_AUTO_INSTALL=1\nRye currently uses build to build the package and uses twine to publish it.
"},{"location":"guide/publish/#build","title":"Build","text":"By default, rye will build both the sdist and wheel targets in the dist directory. The command for this is called build.
rye build\nYou can use the --sdist or --wheel flag to build the specific target, or specify the output directory with --out.
rye build --wheel --out target\nIf you want to clean the build directory before building, run:
rye build --clean\nRye will publish the distribution files under the dist directory to PyPI by default.
rye publish\nYou 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/\nAccess token:\nYou can also specify the distribution files to be published:
rye publish dist/example-0.1.0.tar.gz\nRye 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/\nYou can optionally set the --yes flag to skip the confirmation prompt. This can be useful for CI/CD pipelines.
rye publish --token <your_token> --yes\nRye will store your repository info in $HOME/.rye/credentials for future use.
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.
pyproject.toml)","text":"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","text":"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]\ndependencies = [\n\"mkdocs~=1.4.3\",\n\"mkdocs-material~=9.1.12\",\n\"pymdown-extensions~=9.11\",\n]\nproject.scripts","text":"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]\nmy-hello-script = 'hello:main'\nmy-hello-script that will call the main function of the hello module. Scripts can be installed using rye sync and run using rye run:
$ rye sync\n$ rye run my-hello-script\nHello from hello!\ntool.rye.dev-dependencies","text":"This works similar to project.dependencies but holds development only dependencies. These can be added here automatically via rye add --dev.
[tool.rye]\ndev-dependencies = [\"black~=23.3.0\"]\nDev dependencies are installed automatically unless --no-dev is passed to sync.
tool.rye.excluded-dependencies","text":"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]\nexcluded-dependencies = [\"cffi\"]\ntool.rye.universal","text":"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]\nuniversal = true\ntool.rye.generate-hashes","text":"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]\ngenerate-hashes = true\ntool.rye.lock-with-sources","text":"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]\nlock-with-sources = true\ntool.rye.managed","text":"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]\nmanaged = true\ntool.rye.virtual","text":"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]\nvirtual = true\nFor more information consult the Virtual Project Guide.
"},{"location":"guide/pyproject/#toolryesources","title":"tool.rye.sources","text":"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]]\nname = \"default\"\nurl = \"http://pypi.org/simple/\"\nFor more information about configuring sources see Dependency Sources.
"},{"location":"guide/pyproject/#toolryescripts","title":"tool.rye.scripts","text":"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]\n# These three options are equivalent:\ndevserver = \"flask run --app ./hello.py --debug\"\ndevserver-alt = [\"flask\", \"run\", \"--app\", \"./hello.py\", \"--debug\"]\ndevserver-explicit = { cmd = \"flask run --app ./hello.py --debug\" }\nThe following keys are possible for a script:
"},{"location":"guide/pyproject/#cmd","title":"cmd","text":"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]\ndevserver = { cmd = \"flask run --app ./hello.py --debug\" }\nhttp = { cmd = [\"python\", \"-mhttp.server\", \"8000\"] }\nenv","text":"This key can be used to provide environment variables with a script:
[tool.rye.scripts]\ndevserver = { cmd = \"flask run --debug\", env = { FLASK_APP = \"./hello.py\" } }\nenv-file","text":"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]\ndevserver = { cmd = \"flask run --debug\", env-file = \".dev.env\" }\nchain","text":"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]\nlint = { chain = [\"lint:black\", \"lint:flake8\" ] }\n\"lint:black\" = \"black --check src\"\n\"lint:flake8\" = \"flake8 src\"\ncall","text":"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:
<module_name>: equivalent to python -m <module_name><module_name>:<function_name>: runs <function_name> from <module_name> and exits with the return value<module_name>:<function_name>(<args>): passes specific arguments to the functionExtra arguments provided on the command line are passed in sys.argv.
[tool.rye.scripts]\nserve = { call = \"http.server\" }\nhelp = { call = \"builtins:help\" }\nhello-world = { call = \"builtins:print('Hello World!')\" }\ntool.rye.workspace","text":"When a table with that key is stored, then a project is declared to be a workspace 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]\nmembers = [\"mylib-*\"]\nFor more information consult the Workspaces Guide.
"},{"location":"guide/rust/","title":"Rust Modules","text":"Rye recommends using maturin to develop Rust Python extension modules. This process is largely automated and new projects can be created with rye init.
rye init my-project --build-system maturin\ncd my-project\nThe following structure will be created:
.\n\u251c\u2500\u2500 .git\n\u251c\u2500\u2500 .gitignore\n\u251c\u2500\u2500 .python-version\n\u251c\u2500\u2500 README.md\n\u251c\u2500\u2500 pyproject.toml\n\u251c\u2500\u2500 Cargo.toml\n\u251c\u2500\u2500 python\n \u2514\u2500\u2500 my_project\n \u2514\u2500\u2500 __init__.py\n\u2514\u2500\u2500 src\n \u2514\u2500\u2500 lib.rs\nWhen 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\nNote that maturin develop requires pip to be installed into the virtualenv. Before you can use it you need to add it:
rye add --dev pip\nrye sync\nRye 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\nAfter 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.
"},{"location":"guide/shims/#global-shims","title":"Global Shims","text":"new in 0.9.0
To enable global shims, you need to enable the global-python flag in the config.toml file:
rye config --set-bool behavior.global-python=true\nAfterwards 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\nNote
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.
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.
"},{"location":"guide/sources/#adding-a-source","title":"Adding a Source","text":"An index can be added to a project or workspace (via pyproject.toml) or into the global config. 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.
Add this to ~/.rye/config.toml:
[[sources]]\nname = \"company-internal\"\nurl = \"https://company.internal/simple/\"\nAdd this to pyproject.toml:
[[tool.rye.sources]]\nname = \"company-internal\"\nurl = \"https://company.internal/simple/\"\nchanged in 0.4.0
Sources in the global config are also considered for tool installations.
"},{"location":"guide/sources/#index-types","title":"Index Types","text":"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.
[[sources]]\nname = \"company-internal\"\nurl = \"https://company.internal/simple/\"\ntype = \"index\" # this is implied\n[[sources]]\nname = \"company-internal\"\nurl = \"https://company.internal/\"\ntype = \"find-links\"\n[[sources]]\nname = \"default\"\nurl = \"https://company.internal/simple/\"\nWarning
Please take note that the default index cannot be of type find-links.
The two sources types (index vs find-links) are determined by the underlying pip infrastructure:
index","text":"This is a PEP 503 type index as provided by tools such as PyPI or devpi. It corresponds to the arguments --index-url or --extra-index-url in pip.
Note: see the uv documentation for more on the use of multiple indexes.
find-links","text":"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.
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.
[[sources]]\nname = \"company-internal\"\nurl = \"https://company.internal/simple/\"\nusername = \"username\"\npassword = \"super secret\"\n[[sources]]\nname = \"company-internal\"\nurl = \"https://${INDEX_USERNAME}:${INDEX_PASSWORD}@company.internal/simple/\"\nBy 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]]\nname = \"company-internal\"\nurl = \"http://company.internal/simple/\"\nverify-ssl = false\nRye supports two systems to manage dependencies: uv and pip-tools. It currently defaults to uv as it offers significantly better performance, but will offer you the option to use pip-tools instead.
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.
When locking, some options can be provided to change the locking behavior. These flags are also all available on rye sync.
--update / --update-all","text":"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\n--features / --all-features","text":"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\nrye lock --features=web\nWhen working with workspaces, the package name needs to be prefixed with a slash:
rye lock --features=package-name/feature-name\nThe --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\n--pre","text":"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\n--with-sources","text":"new in 0.18.0
By default (unless the tool.rye.lock-with-sources config key is set to true in the pyproject.toml) lock files are not generated with source references. This means that if custom sources are used the lock file cannot be installed via pip unless also --find-links and other parameters are manually passed. This can be particularly useful when the lock file is used for docker image builds.
When this flag is passed then the lock file is generated with references to --index-url, --extra-index-url or --find-links.
rye lock --with-sources\nSyncing 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","text":"To prevent the lock step from automatically running, pass --no-lock.
rye sync --no-lock\n--no-dev","text":"Only sync based on the production lockfile (requirements.lock) instead of the development lockfile (requirements-dev.lock).
rye sync --no-dev\nLockfiles depend on the platform they were generated on. This is a known limitation in pip-tools.
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.
"},{"location":"guide/tools/","title":"Tools","text":"Rye supports global tool installations. This for instance allows you to install tools like black or ruff globally.
Use the rye tools install (aliased to rye install) command to install a tool globally with a shim:
rye install ruff\nAfterwards 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.
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\nIf 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\nIf you want to see which tools are installed, you can use rye tools list:
rye tools list\nblack\n black\n blackd\nruff\n ruff\nTo also see which scripts those tools provide, also pass --include-scripts
rye tools list --include-scripts\nTo uninstall a tool again, use rye tools uninstall (aliased to rye uninstall):
rye uninstall black\nnew 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\nrye add mkdocs\nrye sync\nrye run mkdocs\nThis 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.
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.
"},{"location":"guide/virtual/#limitations","title":"Limitations","text":"Virtual projects can not have optional dependencies. These even if declared are not installed.
"},{"location":"guide/virtual/#workspaces","title":"Workspaces","text":"If a workspace does not have a toplevel package it's recommended that it's declared as virtual.
"},{"location":"guide/workspaces/","title":"Workspaces","text":"Workspaces are a feature that allows you to work with multiple packages that have dependencies to each other. A workspace is declared by setting the tool.rye.workspace key a pyproject.toml. Afterwards all projects within that workspace share a singular virtualenv.
A workspace is declared by the \"toplevel\" pyproject.toml. At the very least the key tool.rye.workspace needs to be added. It's recommended that a glob pattern is also set in the members key to prevent accidentally including unintended folders as projects.
[tool.rye.workspace]\nmembers = [\"myname-*\"]\nThis declares a workspace where all folders starting with the name myname- are considered. If the toplevel workspace in itself should not be a project, then it should be declared as a virtual package:
[tool.rye]\nvirtual = true\n\n[tool.rye.workspace]\nmembers = [\"myname-*\"]\nFor more information on that see Virtual Packages.
"},{"location":"guide/workspaces/#syncing","title":"Syncing","text":"In a workspace it does not matter which project you are working with, the entire workspace is synchronized at all times. This has some untypical 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\nThis is a list of all the commands that rye provides:
The toplevel rye command accepts the following options:
--env-file <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.add","text":"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 command or pass --sync. To remove a dependency again use the remove command.
new in 0.26.0
Added support for auto-sync and the --sync / --no-sync flags.
Add the latest version of a dependency that is compatible with the configured Python version:
$ rye add flask\nAdded flask>=3.0.1 as regular dependency\nAdd a dependency but add an optional extra feature:
$ rye add flask --features dotenv\nAdded flask[dotenv]>=3.0.1 as regular dependency\nAdd a git dependency:
$ rye add flask --git https://github.com/pallets/flask\nAdded flask @ git+https://github.com/pallets/flask as regular dependency\nAdd a local dependency:
$ rye add packagename --path path/to/packagename\nAdded packagename @ file:///path/to/packagename as regular dependency\n<REQUIREMENTS>...: The package to add as PEP 508 requirement string. e.g. 'flask==2.2.3'--git <GIT>: Install the given package from this git repository
--url <URL>: Install the given package from this URL
--path <PATH>: Install the given package from this local path
--absolute: Force non interpolated absolute paths
--tag <TAG>: Install a specific tag
--rev <REV>: Update to a specific git rev
--branch <BRANCH>: Update to a specific git branch
--features <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 <OPTIONAL>: Add this to an optional dependency group
--pre: Include pre-releases when finding a package version
--pin <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)
build","text":"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.
"},{"location":"guide/commands/build/#example","title":"Example","text":"This builds wheels and source distributions at once:
$ rye build\nbuilding my-project\n* Creating virtualenv isolated environment...\n* Installing packages in isolated environment... (hatchling)\n* Getting build dependencies for sdist...\n* Building sdist...\n* Building wheel from sdist\n* Creating virtualenv isolated environment...\n* Installing packages in isolated environment... (hatchling)\n* Getting build dependencies for wheel...\n* Building wheel...\nSuccessfully built my_project-0.1.0.tar.gz and my_project-0.1.0-py3-none-any.whl\nBy default you will find the artifacts in the dist folder.
no arguments
"},{"location":"guide/commands/build/#options","title":"Options","text":"--sdist: Build an sdist
--wheel: Build a wheel
-a, --all: Build all packages
-p, --package <PACKAGE>: Build a specific package
-o, --out <OUT>: An output directory (defaults to workspace/dist)
--pyproject <PYPROJECT_TOML>: 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
config","text":"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.
This command turns on global shims:
rye config --set-bool behavior.global-python=true\nReads the currently set config value for global Python shims:
$ rye config --get behavior.global-python\ntrue\nShow the path to the config:
$ rye config --show-path\n/Users/username/.rye/config.toml\nno arguments
"},{"location":"guide/commands/config/#options","title":"Options","text":"--get <GET>: Reads a config key
--set <SET>: Sets a config key to a string
--set-int <SET_INT>: Sets a config key to an integer
--set-bool <SET_BOOL>: Sets a config key to a bool
--unset <UNSET>: Remove a config key
--show-path: Print the path to the config
--format <FORMAT>: Request parseable output format rather than lines
[possible values: json]
-h, --help: Print help (see a summary with '-h')
fetch","text":"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.
"},{"location":"guide/commands/fetch/#example","title":"Example","text":"Fetch a specific version of Python:
$ rye fetch 3.8.13\nDownloading cpython@3.8.13\nChecking checksum\nUnpacking\nDownloaded cpython@3.8.13\nTo fetch the pinned version of Python you can leave out the argument:
$ rye fetch\nDownloading cpython@3.8.17\nChecking checksum\nUnpacking\nDownloaded cpython@3.8.17\nTo fetch a version of Python into a specific location rather than rye's interpreter cache:
$ rye fetch cpython@3.9.1 --target-path=my-interpreter\n[VERSION]: The version of Python to fetch.
If no version is provided, the requested version will be fetched.
-f, --force: Fetch the Python toolchain even if it is already installed.
--target-path <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')
fmt","text":"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.
"},{"location":"guide/commands/fmt/#example","title":"Example","text":"To format the code and write back to the files:
$ rye fmt\n1 file reformatted, 231 files left unchanged\nTo just check if the code needs formatting:
$ rye fmt --check\nWould reformat: src/my_project/utils.py\n1 file would be reformatted, 231 files already formatted\nTo pass extra arguments to the underlying ruff formatter use --:
$ rye fmt -- --diff\n--- src/my_project/utils.py\n+++ src/my_project/utils.py\n@@ -2,5 +2,4 @@\n\n\n def foo():\n-\n pass\n\n1 file would be reformatted, 231 files already formatted\nFormat a specific file:
rye fmt src/foo.py\n[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.
-a, --all: Format all packages in the workspace
-p, --package <PACKAGE>: Format a specific package
--pyproject <PYPROJECT_TOML>: 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')
init","text":"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.
"},{"location":"guide/commands/init/#example","title":"Example","text":"$ rye init\nsuccess: Initialized project in /Users/john/Development/my-project.\n Run `rye sync` to get started\n[PATH]: Where to place the project (defaults to current path)--min-py <MIN_PY>: Minimal Python version supported by this project
-p, --py <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 <BUILD_SYSTEM>: Which build system should be used(defaults to hatchling)?
[possible values: hatchling, setuptools, flit, pdm, maturin]
--license <LICENSE>: Which license should be used? SPDX identifier
--name <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_FILE>: Requirements files to initialize pyproject.toml with
--dev-requirements <DEV_REQUIREMENTS_FILE>: 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')
install","text":"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.
"},{"location":"guide/commands/install/#example","title":"Example","text":"$ rye tools install pycowsay\nLooking in indexes: https://pypi.org/simple/\nCollecting pycowsay\n Downloading pycowsay-0.0.0.2-py3-none-any.whl.metadata (965 bytes)\nDownloading pycowsay-0.0.0.2-py3-none-any.whl (4.0 kB)\nInstalling collected packages: pycowsay\nSuccessfully installed pycowsay-0.0.0.2\n\nInstalled scripts:\n - pycowsay\n\n$ pycowsay \"Great Stuff\"\n\n -----------\n< Great Stuff >\n -----------\n \\ ^__^\n \\ (oo)\\_______\n (__)\\ )\\/\\\n ||----w |\n || ||\n<REQUIREMENT>...: The package to install as PEP 508 requirement string.--git <GIT>: Install the given package from this git repository
--url <URL>: Install the given package from this URL
--path <PATH>: Install the given package from this local path
--absolute: Force non interpolated absolute paths
--tag <TAG>: Install a specific tag
--rev <REV>: Update to a specific git rev
--branch <BRANCH>: Update to a specific git branch
--features <FEATURES>: Adds a dependency with a specific feature
--include-dep <INCLUDE_DEP>: Include scripts from a given dependency
--extra-requirement <EXTRA_REQUIREMENT>: Additional dependencies to install that are not declared by the main package
-p, --python <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')
lint","text":"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.
"},{"location":"guide/commands/lint/#example","title":"Example","text":"Run the linter:
$ rye lint\nsrc/myproject/sdk.py:1:8: F401 [*] `sys` imported but unused\nFound 1 error.\n[*] 1 fixable with the `--fix` option.\nFor issues that can be auto fixed pass --fix:
$ rye lint --fix\nFound 1 error (1 fixed, 0 remaining).\nTo pass extra arguments:
$ rye lint -- --watch\nLint a specific file:
rye lint src/foo.py\n[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.
-a, --all: Lint all packages in the workspace
-p, --package <PACKAGE>: Format a specific package
--pyproject <PYPROJECT_TOML>: 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')
list","text":"new in 0.24.0
Prints a list of installed dependencies.
"},{"location":"guide/commands/list/#example","title":"Example","text":"$ rye list\nasgiref==3.7.2\nblinker==1.7.0\nclick==8.1.7\nFlask @ git+https://github.com/pallets/flask@4df377cfbfc1d15e962a61c18920b22aebc9aa41\nitsdangerous==2.1.2\nJinja2==3.1.3\nMarkupSafe==2.1.4\nWerkzeug==3.0.1\nno arguments
"},{"location":"guide/commands/list/#options","title":"Options","text":"--pyproject: Use this pyproject.toml file
-h, --help: Print help (see a summary with '-h')
lock","text":"Updates the lockfiles without installing dependencies. Usually one would use the sync command instead which both locks and installs dependencies.
For more information see Syncing and Locking.
"},{"location":"guide/commands/lock/#example","title":"Example","text":"$ rye lock\nGenerating production lockfile: /Users/username/my-project/requirements.lock\nGenerating dev lockfile: /Users/username/my-project/requirements-dev.lock\nDone!\nno arguments
"},{"location":"guide/commands/lock/#options","title":"Options","text":"--update <UPDATE>: Update a specific package
--update-all: Update all packages to the latest
--pre: Update to pre-release versions
--features <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 <PYPROJECT_TOML>: 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')
make-req","text":"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 but rather than adding the requirements into the requirements file it just spits out a formatted PEP 508 requirement string on stdout.
$ rye make-req flask --git https://github.com/pallets/flask --rev 4df377cfbf\nflask @ git+https://github.com/pallets/flask@4df377cfbf\n[REQUIREMENTS]... The package to add as PEP 508 requirement string. e.g. 'flask==2.2.3'--git <GIT>: Install the given package from this git repository
--url <URL>: Install the given package from this URL
--path <PATH>: Install the given package from this local path
--absolute: Force non interpolated absolute paths
--tag <TAG>: Install a specific tag
--rev <REV>: Update to a specific git rev
--branch <BRANCH>: Update to a specific git branch
--features <FEATURES>: Adds a dependency with a specific feature
-h, --help: Print help (see a summary with '-h')
pin","text":"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.
"},{"location":"guide/commands/pin/#example","title":"Example","text":"Pin a specific version of Python:
$ rye pin 3.9\npinned 3.9.18 in /Users/username/my-project\nTo issue a relaxed and not a specific pin use --relaxed:
$ rye pin 3.9 --relaxed\npinned 3.9 in /Users/username/my-project\n<VERSION>: The version of Python to pin
This can be a short version (3.9) or a full one (cpython@3.9.18).
--relaxed: Issue a relaxed pin
--no-update-requires-python: Prevent updating requires-python in the pyproject.toml
--pyproject <PYPROJECT_TOML>: Use this pyproject.toml file
-h, --help: Print help (see a summary with '-h')
publish","text":"Publish packages to a package repository. This publishes the packages which are produced by the build command.
For more information see Building and Publishing.
"},{"location":"guide/commands/publish/#example","title":"Example","text":"Build and publish:
$ rye build\n$ rye publish\nPublish a specific artifact:
$ rye publish dist/example-0.1.0.tar.gz\n[DIST]...: The distribution files to upload to the repository (defaults to <workspace-root>/dist/*)-r, --repository <REPOSITORY>: The repository to publish to [default: pypi]
--repository-url <REPOSITORY_URL>: The repository url to publish to
-u, --username <USERNAME>: The username to authenticate to the repository with
--token <TOKEN>: An access token used for the upload
--sign: Sign files to upload using GPG
-i, --identity <IDENTITY>: GPG identity used to sign files
--cert <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')
remove","text":"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 command or pass --sync.
new in 0.26.0
Added support for auto-sync and the --sync / --no-sync flags.
$ rye remove flask\nRemoved flask>=3.0.1\n<REQUIREMENTS>...: The packages to remove from the project--dev: Remove this from dev dependencies
--optional <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')
run","text":"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.
Run a tool from the virtualenv:
$ rye run flask\nInvoke it without arguments to see all available scripts:
$ rye run\nflask\nhello\npython\npython3\npython3.9\n[COMMAND]: The name of the command and the arguments to it.-l, --list: List all commands (implied without arguments)
--pyproject: Use this pyproject.toml file
-h, --help: Print help (see a summary with '-h')
show","text":"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.
"},{"location":"guide/commands/show/#example","title":"Example","text":"Print out the status of a project:
$ rye show\nproject: my-project\npath: /Users/username/my-project\nvenv: /Users/username/my-project/.venv\ntarget python: 3.8\nvenv python: cpython@3.9.18\nvirtual: false\nno arguments
"},{"location":"guide/commands/show/#options","title":"Options","text":"--installed-deps: Print the currently installed dependencies.
This option is being replaced with rye list
--pyproject: Use this pyproject.toml file
-h, --help: Print help (see a summary with '-h')
sync","text":"Updates the lockfiles and installs the dependencies into the virtualenv.
For more information see Syncing and Locking.
"},{"location":"guide/commands/sync/#example","title":"Example","text":"Sync the project:
$ rye sync\nReusing already existing virtualenv\nGenerating production lockfile: /Users/username/my-project/requirements.lock\nGenerating dev lockfile: /Users/username/my-project/requirements-dev.lock\nInstalling dependencies\n...\nTo sync without updating the lock file use --no-lock:
$ rye sync --no-lock\nIf you do not want dev dependencies to be installed use --no-dev:
$ rye sync --no-dev\nTo exit the sub shell run exit.
no arguments
"},{"location":"guide/commands/sync/#options","title":"Options","text":"-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>: Update a specific package
--update-all: Update all packages to the latest
--pre: Update to pre-release versions
--features <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 <PYPROJECT_TOML>: 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')
test","text":"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\nIt'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.
"},{"location":"guide/commands/test/#example","title":"Example","text":"Run the test suite:
$ rye test\nplatform win32 -- Python 3.11.1, pytest-8.0.2, pluggy-1.4.0\nrootdir: /Users/john/Development/stuff\nplugins: anyio-4.3.0\ncollected 1 item\n\nstuff/tests/test_batch.py . [100%] \n[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.
-a, --all: Test all packages in the workspace
-p, --package <PACKAGE>: Run the test suite of a specific package
--pyproject <PYPROJECT_TOML>: 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')
uninstall","text":"Uninstalls an already installed global tool. This command has two names to rye tools uninstall and rye uninstall.
For more information see Tools.
"},{"location":"guide/commands/uninstall/#example","title":"Example","text":"$ rye tools uninstall pycowsay\nUninstalled pycowsay\n<NAME>: The package to uninstall.-v, --verbose: Enables verbose diagnostics
-q, --quiet: Turns off all output
-h, --help: Print help (see a summary with '-h')
version","text":"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.
Get the current version:
$ rye version\n0.1.0\nBump the version by minor:
$ rye version -b minor\nversion bumped to 0.2.0\nSet to a specific version:
$ rye version 1.0.0\nversion set to 1.0.0\n[VERSION]: the version to set-b, --bump <BUMP>: automatically bump the version in a specific way (major, minor or patch)
-h, --help: Print help (see a summary with '-h')
self","text":"Command to manage Rye itself.
completion: Generates a completion script for Rye.
update: Performs an update of Rye.
uninstall: Uninstalls Rye again.
completion","text":"Generates a completion script for a shell
"},{"location":"guide/commands/self/completion/#example","title":"Example","text":"Generate a completion script for zsh and load it:
$ eval \"$(rye self completion -s zsh)\"\nno arguments
"},{"location":"guide/commands/self/completion/#options","title":"Options","text":"-s, --shell <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')
uninstall","text":"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.
Uninstall rye without asking:
$ rye self uninstall --yes\nno arguments
"},{"location":"guide/commands/self/uninstall/#options","title":"Options","text":"-y, --yes: Do not prompt and uninstall.
-h, --help: Print help (see a summary with '-h')
update","text":"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.
"},{"location":"guide/commands/self/update/#example","title":"Example","text":"Update to the latest version:
$ rye self update\nUpdate (or downgrade) to a specific version:
$ rye self update --version 0.20\nCompile a specific revision:
$ rye self update --rev 08910bc9b3b7c72a3d3ac694c4f3412259161477\nCompile latest development version:
$ rye self update --branch main\nno arguments
"},{"location":"guide/commands/self/update/#options","title":"Options","text":"--version <VERSION>: Update to a specific version
--tag <TAG>: Update to a specific tag
--rev <REV>: Update to a specific git rev
--branch <BRANCH>: Update to a specific git branch
--force: Force reinstallation
-h, --help: Print help (see a summary with '-h')
toolchain","text":"Helper utility to manage Python toolchains. The following subcommands exist:
fetch: fetches a toolchain
list: lists all registered toolchains
register: register a Python binary as custom toolchain
remove: removes or uninstalls a toolchain
fetch","text":"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.
"},{"location":"guide/commands/toolchain/fetch/#example","title":"Example","text":"Fetch a specific version of Python:
$ rye fetch 3.8.13\nDownloading cpython@3.8.13\nChecking checksum\nUnpacking\nDownloaded cpython@3.8.13\nTo fetch the pinned version of Python you can leave out the argument:
$ rye fetch\nDownloading cpython@3.8.17\nChecking checksum\nUnpacking\nDownloaded cpython@3.8.17\nTo fetch a version of Python into a specific location rather than rye's interpreter cache:
$ rye fetch cpython@3.9.1 --target-path=my-interpreter\n[VERSION]: The version of Python to fetch.
If no version is provided, the requested version will be fetched.
-f, --force: Fetch the Python toolchain even if it is already installed.
--target-path <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')
list","text":"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.
List installed toolchains:
$ rye toolchain list\ncpython@3.12.1 (/Users/username/.rye/py/cpython@3.12.1/install/bin/python3)\ncpython@3.11.6 (/Users/username/.rye/py/cpython@3.11.6/install/bin/python3)\nLists downloadable toolchains:
$ rye toolchain list --include-downloadable\ncpython@3.12.1 (/Users/mitsuhiko/.rye/py/cpython@3.12.1/install/bin/python3)\ncpython-x86_64@3.12.1 (downloadable)\ncpython@3.11.7 (downloadable)\n...\nno arguments
"},{"location":"guide/commands/toolchain/list/#options","title":"Options","text":"--include-downloadable: Also include non installed, but downloadable toolchains
--format <FORMAT>: Request parseable output format [possible values: json]
-h, --help: Print help
register","text":"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 command.
$ rye toolchain register /opt/homebrew/Cellar/python@3.10/3.10.6_1/bin/python3.10\nRegistered /opt/homebrew/Cellar/python@3.10/3.10.6_1/bin/python3.10 as cpython@3.10.6\n<PATH>: Path to the python binary that should be registered-n, --name <NAME>: Name of the toolchain. If not provided a name is auto detected.
-h, --help: Print help (see a summary with '-h')
remove","text":"Removes or uninstalls a toolchain.
"},{"location":"guide/commands/toolchain/remove/#example","title":"Example","text":"$ rye toolchain remove 3.9.5\nRemoved installed toolchain cpython@3.9.5\n<VERSION> The version of Python to remove.-f, --force: Force removal even if the toolchain is in use-h, --help: Print help (see a summary with '-h')tools","text":"Helper utility to manage global tool installations.
install: installs a tool globally.
uninstall: uninstalls a globally installed tool.
list: lists all globally installed tools.
install","text":"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.
"},{"location":"guide/commands/tools/install/#example","title":"Example","text":"$ rye tools install pycowsay\nLooking in indexes: https://pypi.org/simple/\nCollecting pycowsay\n Downloading pycowsay-0.0.0.2-py3-none-any.whl.metadata (965 bytes)\nDownloading pycowsay-0.0.0.2-py3-none-any.whl (4.0 kB)\nInstalling collected packages: pycowsay\nSuccessfully installed pycowsay-0.0.0.2\n\nInstalled scripts:\n - pycowsay\n\n$ pycowsay \"Great Stuff\"\n\n -----------\n< Great Stuff >\n -----------\n \\ ^__^\n \\ (oo)\\_______\n (__)\\ )\\/\\\n ||----w |\n || ||\n<REQUIREMENT>...: The package to install as PEP 508 requirement string.--git <GIT>: Install the given package from this git repository
--url <URL>: Install the given package from this URL
--path <PATH>: Install the given package from this local path
--absolute: Force non interpolated absolute paths
--tag <TAG>: Install a specific tag
--rev <REV>: Update to a specific git rev
--branch <BRANCH>: Update to a specific git branch
--features <FEATURES>: Adds a dependency with a specific feature
--include-dep <INCLUDE_DEP>: Include scripts from a given dependency
--extra-requirement <EXTRA_REQUIREMENT>: Additional dependencies to install that are not declared by the main package
-p, --python <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')
list","text":"Lists all already installed global tools.
For more information see Tools.
"},{"location":"guide/commands/tools/list/#example","title":"Example","text":"List installed tools:
$ rye tools list\npycowsay\nList installed tools with version:
$ rye tools list --include-version\npycowsay 0.0.0.2 (cpython@3.12.1)\nno arguments
"},{"location":"guide/commands/tools/list/#options","title":"Options","text":"-s, --include-scripts: Show all the scripts installed by the toolschanged in 0.26.0
Renamed from -i, --include-scripts to -s, --include-scripts.
-v, --include-version: Show the version of toolschanged in 0.26.0
Renamed from -v, --version-show to -v, --include-version.
-h, --help: Print helpuninstall","text":"Uninstalls an already installed global tool. This command has two names to rye tools uninstall and rye uninstall.
For more information see Tools.
"},{"location":"guide/commands/tools/uninstall/#example","title":"Example","text":"$ rye tools uninstall pycowsay\nUninstalled pycowsay\n<NAME>: The package to uninstall.-v, --verbose: Enables verbose diagnostics
-q, --quiet: Turns off all output
-h, --help: Print help (see a summary with '-h')
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:
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 cpython@3.11.4\nPinning 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 cpython@3.11, 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 cpython@3.11\nThis 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.
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 cpython@3.11 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 cpython-x86_64@3.11\nNote that such custom pins are not reflected in pyproject.toml but only .python-version.
To see which toolchains are installed, rye toolchain list prints a list:
rye toolchain list\ncpython@3.11.1 (C:\\Users\\armin\\.rye\\py\\cpython@3.11.1\\install\\python.exe)\npypy@3.9.16 (C:\\Users\\armin\\.rye\\py\\pypy@3.9.16\\python.exe)\nTo see which toolchains can be installed, additionally pass the --include-downloadable:
rye toolchain list --include-downloadable\nGenerally Rye automatically downloads toolchains, but they can be explicitly fetched with rye toolchain fetch (also aliased to rye fetch):
rye toolchain fetch cpython@3.8.5\nStarting 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\nrye fetch\nToolchains are fetched from two sources:
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 cpython@3.8.5 --target-path=my-interpreter\nIf 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.
Additionally, it's possible to register an external toolchain with the rye toolchain register command.
rye toolchain register /path/to/python\nThe 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\nTo remove an already fetched toolchain run rye toolchain remove. Note that this also works for linked toolchains:
rye toolchain remove cpython@3.8.5\nWarning
Removing an actively used toolchain will render the virtualenvs that refer to use broken.
"},{"location":"guide/toolchains/#build-info","title":"Build Info","text":"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 cpython@3.8.5/bin/python3 there you will instead have an extra install folder (cpython@3.8.5/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\nRye 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 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.
"},{"location":"guide/toolchains/cpython/#limitations","title":"Limitations","text":"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. Additionally, the Python Standalone Builds have a Behavior Quirks page.
"},{"location":"guide/toolchains/cpython/#sources","title":"Sources","text":"Portable CPython builds are downloaded from GitHub (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.
"},{"location":"guide/toolchains/cpython/#usage","title":"Usage","text":"When you pin a Python version to cpython@major.minor.patch (or just major.minor.patch) then Rye will automatically download the right version for you whenever it is needed. If a custom toolchain has already been registered with that name and version, that this is used instead.
PyPy is supported as alternative Python distribution. Like the portable CPython builds it's downloaded automatically. The name for PyPy distributions is pypy.
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.
"},{"location":"guide/toolchains/pypy/#sources","title":"Sources","text":"PyPy builds are downloaded from downloads.python.org.
"},{"location":"guide/toolchains/pypy/#usage","title":"Usage","text":"When you pin a Python version to pypy@major.minor.patch then Rye will automatically download the right version for you whenever it is needed. If a custom toolchain 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 pypy@3.9.16 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.