13 |
14 | > [!NOTE]
15 | >
16 | > If you're getting started with Rye, consider [uv](https://github.com/astral-sh/uv), the
17 | > [successor project](https://lucumr.pocoo.org/2024/2/15/rye-grows-with-uv/) from the same maintainers.
18 | >
19 | > While Rye is actively maintained, uv offers a more stable and feature-complete experience, and is the recommended
20 | > choice for new projects.
21 | >
22 | > Having trouble migrating? [Let us know what's missing.](https://github.com/astral-sh/rye/discussions/1342)
23 |
24 | Rye is a comprehensive project and package management solution for Python.
25 | Born from [its creator's](https://github.com/mitsuhiko) desire to establish a
26 | one-stop-shop for all Python users, Rye provides a unified experience to install and manage Python
27 | installations, `pyproject.toml` based projects, dependencies and virtualenvs
28 | seamlessly. It's designed to accommodate complex projects, monorepos and to
29 | facilitate global tool installations. Curious? [Watch an introduction](https://youtu.be/q99TYA7LnuA).
30 |
31 | A hassle-free experience for Python developers at every level.
32 |
33 |
Click on the thumbnail to watch a 16 minute introduction video
38 |
39 |
40 | ## In The Box
41 |
42 | Rye picks and ships the right tools so you can get started in minutes:
43 |
44 | * **Bootstraps Python:** it provides an automated way to get access to the amazing [Indygreg Python Builds](https://github.com/indygreg/python-build-standalone/) as well as the PyPy binary distributions.
45 | * **Linting and Formatting:** it bundles [ruff](https://github.com/astral-sh/ruff) and makes it available with `rye lint` and `rye fmt`.
46 | * **Managing Virtualenvs:** it uses the well established virtualenv library under the hood.
47 | * **Building Wheels:** it delegates that work largely to [build](https://pypi.org/project/build/).
48 | * **Publishing:** its publish command uses [twine](https://pypi.org/project/twine/) to accomplish this task.
49 | * **Locking and Dependency Installation:** is today implemented by using [uv](https://github.com/astral-sh/uv) with a fallback to [unearth](https://pypi.org/project/unearth/) and [pip-tools](https://github.com/jazzband/pip-tools/).
50 | * **Workspace support:** Rye lets you work with complex projects consisting
51 | of multiple libraries.
52 |
53 | ## Installation
54 |
55 | The installation takes just a minute:
56 |
57 | * **Linux and macOS:**
58 |
59 | ```
60 | curl -sSf https://rye.astral.sh/get | bash
61 | ```
62 |
63 | * **Windows:**
64 |
65 | Download and run the installer ([64-bit (x86-64)](https://github.com/astral-sh/rye/releases/latest/download/rye-x86_64-windows.exe) or [32-bit (x86)](https://github.com/astral-sh/rye/releases/latest/download/rye-x86-windows.exe)).
66 |
67 | For more details and other options, refer to the [installation instructions](https://rye.astral.sh/guide/installation/).
68 |
69 | ## Learn More
70 |
71 | Did I spark your interest?
72 |
73 | * [Visit the Website](https://rye.astral.sh/)
74 | * [Read the Documentation](https://rye.astral.sh/guide/)
75 | * [Report Problems in the Issue Tracker](https://github.com/astral-sh/rye/issues)
76 |
77 | ## More
78 |
79 | * [Discussion Forum](https://github.com/astral-sh/rye/discussions), to discuss the project
80 | on GitHub
81 | * [Discord](https://discord.gg/drbkcdtSbg), for conversations with other developers in text form
82 | * [Issue Tracker](https://github.com/astral-sh/rye/issues), if you run into bugs or have suggestions
83 | * [Badges](https://rye.astral.sh/community/#badges), if you want to show that you use Rye
84 | * License: MIT
85 |
--------------------------------------------------------------------------------
/artwork/badge.json:
--------------------------------------------------------------------------------
1 | {
2 | "label": "",
3 | "message": "Rye",
4 | "logoSvg": "",
5 | "logoWidth": 12,
6 | "labelColor": "white",
7 | "color": "#ADC541"
8 | }
--------------------------------------------------------------------------------
/artwork/logo-white.svg:
--------------------------------------------------------------------------------
1 |
--------------------------------------------------------------------------------
/artwork/logo.ai:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/astral-sh/rye/e213938342cd08553a7672a417c4fa821c4d7172/artwork/logo.ai
--------------------------------------------------------------------------------
/artwork/logo.svg:
--------------------------------------------------------------------------------
1 |
--------------------------------------------------------------------------------
/docs/.includes/curl-to-bash-options.md:
--------------------------------------------------------------------------------
1 | The install script that is piped to `bash` can be customized with some environment
2 | variables:
3 |
4 | `RYE_VERSION`
5 |
6 | : Defaults to `latest`. Can be set to an explicit version to install a specific one.
7 |
8 | `RYE_INSTALL_OPTION`
9 |
10 | : Can optionally be set to `"--yes"` to skip all prompts.
11 |
12 | {% include-markdown "../.includes/installer-options.md" %}
13 |
14 | This for instance installs a specific version of Rye without asking questions:
15 |
16 | ```bash
17 | curl -sSf https://rye.astral.sh/get | RYE_VERSION="0.4.0" RYE_INSTALL_OPTION="--yes" bash
18 | ```
--------------------------------------------------------------------------------
/docs/.includes/installer-options.md:
--------------------------------------------------------------------------------
1 | `RYE_TOOLCHAIN`
2 |
3 | : Optionally this environment variable can be set to point to a Python
4 | interpreter that should be used as the internal interpreter. If not
5 | provided a suitable interpreter is automatically downloaded.
6 |
7 | At present only CPython 3.9 to 3.12 are supported.
8 |
9 | `RYE_TOOLCHAIN_VERSION`
10 |
11 | : For Rye 0.22 and later a specific Python version can be picked rather
12 | than the default. This affects the internal toolchain version only.
13 | It's useful for Docker builds where you can set the internal toolchain
14 | to the same as your project to only fetch a single Python.
15 |
16 | At present only CPython 3.9 to 3.12 are supported.
17 |
--------------------------------------------------------------------------------
/docs/.includes/quick-install.md:
--------------------------------------------------------------------------------
1 | === "Linux"
2 |
3 | To install you can run a curl command which will install the right binary for your
4 | operating system and CPU architecture and install it:
5 |
6 | ```bash
7 | curl -sSf https://rye.astral.sh/get | bash
8 | ```
9 |
10 | Alternatively if you don't trust this approach, you can download the latest release
11 | binary. On first run it will install itself.
12 |
13 | * [rye-x86_64-linux.gz](https://github.com/astral-sh/rye/releases/latest/download/rye-x86_64-linux.gz) Intel/AMD (x86-64).
14 | * [rye-aarch64-linux.gz](https://github.com/astral-sh/rye/releases/latest/download/rye-aarch64-linux.gz) for ARM64.
15 |
16 | ```bash
17 | gunzip rye-x86_64-linux.gz
18 | chmod +x ./rye-x86_64-linux
19 | ./rye-x86_64-linux
20 | ```
21 |
22 | === "macOS"
23 |
24 | To install you can run a curl command which will install the right binary for your
25 | operating system and CPU architecture and install it:
26 |
27 | ```bash
28 | curl -sSf https://rye.astral.sh/get | bash
29 | ```
30 |
31 | Alternatively if you don't trust this approach, you can download the latest release
32 | binary. On first run it will install itself.
33 |
34 | * [rye-aarch64-macos.gz](https://github.com/astral-sh/rye/releases/latest/download/rye-aarch64-macos.gz) for Apple Silicon (M1/M2/M3) (ARM64).
35 | * [rye-x86_64-macos.gz](https://github.com/astral-sh/rye/releases/latest/download/rye-x86_64-macos.gz) for Intel processors (x86-64).
36 |
37 | ```bash
38 | gunzip rye-aarch64-macos.gz
39 | chmod +x ./rye-aarch64-macos
40 | ./rye-aarch64-macos
41 | ```
42 |
43 | === "Windows"
44 |
45 | To install Rye on windows download the latest release and run the binary. Upon
46 | first run it will install itself. Please note that it's strongly recommended
47 | to have "Developer Mode" activated when using Rye and before starting the
48 | installation. [Learn more](../guide/faq.md).
49 |
50 | * [rye-x86_64-windows.exe](https://github.com/astral-sh/rye/releases/latest/download/rye-x86_64-windows.exe) for 64-bit (x86-64).
51 | * [rye-x86-windows.exe](https://github.com/astral-sh/rye/releases/latest/download/rye-x86-windows.exe) for 32-bit (x86).
52 |
53 | !!!Note
54 |
55 | Rye does not yet use signed binaries which means that you will need to allow
56 | the execution of the downloaded executable. If there is no obvious way to do so, click
57 | on "More info" on the error message that shows up and then on "Run anyway".
58 |
59 | Additionally sometimes a Trojan warning about "Bearfoos" is shown. This is a false
60 | positive. For more information see the discussion [Windows Bearfoos
61 | virus associated with rye](https://github.com/astral-sh/rye/issues/468).
62 |
63 | === "Compile Yourself"
64 |
65 | You need to have Rust and Cargo installed. If you don't have, you can use
66 | [rustup](https://rustup.rs/) to get them onto your machine.
67 |
68 | Afterwards you can install `Rye` via `cargo`:
69 |
70 | ```bash
71 | cargo install --git https://github.com/astral-sh/rye rye
72 | ```
73 |
--------------------------------------------------------------------------------
/docs/.overrides/main.html:
--------------------------------------------------------------------------------
1 | {% extends "base.html" %}
2 |
3 | {% block hero %}
4 |
16 | {% endblock %}
17 |
18 | {% block extrahead %}
19 | {{ super() }}
20 |
50 | {% endblock %}
--------------------------------------------------------------------------------
/docs/CNAME:
--------------------------------------------------------------------------------
1 | rye.astral.sh
2 |
--------------------------------------------------------------------------------
/docs/changelog.md:
--------------------------------------------------------------------------------
1 | # Changelog
2 |
3 | Here you can find all the released changes to Rye. If you want to also see
4 | the in-development changes that were not released yet, refer to the
5 | [CHANGELOG.md](https://github.com/astral-sh/rye/blob/main/CHANGELOG.md) file
6 | in the repository.
7 |
8 | {%
9 | include-markdown "../CHANGELOG.md"
10 | start=""
11 | %}
12 |
--------------------------------------------------------------------------------
/docs/community.md:
--------------------------------------------------------------------------------
1 | ---
2 | hide:
3 | - navigation
4 | ---
5 |
6 | # Community
7 |
8 | Rye is a new project and feedback is greatly appreciated. Lots of it. Because
9 | of this there are various different ways in which you can engage with either
10 | the developer or other members of the community:
11 |
12 | * [Discussion Forum](https://github.com/astral-sh/rye/discussions), to discuss the project
13 | on GitHub
14 | * [Discord](https://discord.gg/drbkcdtSbg), for conversations with other developers in text form
15 | * [Issue Tracker](https://github.com/astral-sh/rye/issues), if you run into bugs or have suggestions
16 |
17 | You can also reach out [via Twitter](https://twitter.com/mitsuhiko) or
18 | [Bluesky](https://bsky.app/profile/mitsuhiko.at).
19 |
20 | ## Badges
21 |
22 | Want to show that you are using Rye? Why not throw a badge into your project's `README.md`:
23 |
24 | ```md
25 | [](https://rye.astral.sh)
26 | ```
27 |
28 | ... or `README.rst`:
29 |
30 | ```rst
31 | .. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/rye/main/artwork/badge.json
32 | :target: https://rye.astral.sh
33 | :alt: Rye
34 | ```
35 |
36 | ... or, as HTML:
37 |
38 | ```html
39 |
40 | ```
41 |
42 | [](https://rye.astral.sh)
43 |
--------------------------------------------------------------------------------
/docs/guide/commands/add.md:
--------------------------------------------------------------------------------
1 | # `add`
2 |
3 | Adds a Python package to this project. The command takes a PEP 508 requirement string
4 | but provides additional helper arguments to make this process more user friendly. For
5 | instance instead of passing git references within the requirement string, the `--git`
6 | parameter can be used.
7 |
8 | If auto sync is disabled, after a dependency is added it's not automatically
9 | installed. To do that, you need to invoke the [`sync`](sync.md) command or pass
10 | `--sync`. To remove a dependency again use the [`remove`](remove.md) command.
11 |
12 | +++ 0.26.0
13 |
14 | Added support for auto-sync and the `--sync` / `--no-sync` flags.
15 |
16 | ## Example
17 |
18 | Add the latest version of a dependency that is compatible with the configured Python version:
19 |
20 | ```
21 | $ rye add flask
22 | Added flask>=3.0.1 as regular dependency
23 | ```
24 |
25 | Add a dependency but add an optional extra feature:
26 |
27 | ```
28 | $ rye add flask --features dotenv
29 | Added flask[dotenv]>=3.0.1 as regular dependency
30 | ```
31 |
32 | Add a git dependency:
33 |
34 | ```
35 | $ rye add flask --git https://github.com/pallets/flask
36 | Added flask @ git+https://github.com/pallets/flask as regular dependency
37 | ```
38 |
39 | Add a local dependency:
40 |
41 | ```
42 | $ rye add packagename --path path/to/packagename
43 | Added packagename @ file:///path/to/packagename as regular dependency
44 | ```
45 |
46 | ## Arguments
47 |
48 | * `...`: The package to add as PEP 508 requirement string. e.g. 'flask==2.2.3'
49 |
50 | ## Options
51 |
52 | * `--git `: Install the given package from this git repository
53 |
54 | * `--url `: Install the given package from this URL
55 |
56 | * `--path `: Install the given package from this local path
57 |
58 | * `--absolute`: Force non interpolated absolute paths
59 |
60 | * `--tag `: Install a specific tag
61 |
62 | * `--rev `: Update to a specific git rev
63 |
64 | * `--branch `: Update to a specific git branch
65 |
66 | * `--features `: Adds a dependency with a specific feature
67 |
68 | * `--dev`: Add this as dev dependency
69 |
70 | * `--excluded`: Add this as an excluded dependency that will not be installed even if it's a sub dependency
71 |
72 | * `--optional `: Add this to an optional dependency group
73 |
74 | * `--pre`: Include pre-releases when finding a package version
75 |
76 | * `--pin `: Overrides the pin operator [possible values: `equal`, `tilde-equal`, `greater-than-equal`]
77 |
78 | * `--sync`: Runs `sync` automatically even if auto-sync is disabled.
79 |
80 | * `--no-sync`: Does not run `sync` automatically even if auto-sync is enabled.
81 |
82 | * `-v, --verbose`: Enables verbose diagnostics
83 |
84 | * `-q, --quiet`: Turns off all output
85 |
86 | * `-h, --help`: Print help (see a summary with `-h`)
87 |
--------------------------------------------------------------------------------
/docs/guide/commands/build.md:
--------------------------------------------------------------------------------
1 | # `build`
2 |
3 | Builds a package for distribution.
4 |
5 | Under normal circumstances Rye automatically builds packages for
6 | local development. However if you want to publish packages you need
7 | to first build them into source distributions (`sdist`) and
8 | binary/portable distributions (`wheel`).
9 |
10 | For more information see [Building and Publishing](../publish.md).
11 |
12 | ## Example
13 |
14 | This builds wheels and source distributions at once:
15 |
16 | ```
17 | $ rye build
18 | building my-project
19 | * Creating virtualenv isolated environment...
20 | * Installing packages in isolated environment... (hatchling)
21 | * Getting build dependencies for sdist...
22 | * Building sdist...
23 | * Building wheel from sdist
24 | * Creating virtualenv isolated environment...
25 | * Installing packages in isolated environment... (hatchling)
26 | * Getting build dependencies for wheel...
27 | * Building wheel...
28 | Successfully built my_project-0.1.0.tar.gz and my_project-0.1.0-py3-none-any.whl
29 | ```
30 |
31 | By default you will find the artifacts in the `dist` folder.
32 |
33 | ## Arguments
34 |
35 | *no arguments*
36 |
37 | ## Options
38 |
39 | * `--sdist`: Build an sdist
40 |
41 | * `--wheel`: Build a wheel
42 |
43 | * `-a, --all`: Build all packages
44 |
45 | * `-p, --package `: Build a specific package
46 |
47 | * `-o, --out `: An output directory (defaults to `workspace/dist`)
48 |
49 | * `--pyproject `: Use this `pyproject.toml` file
50 |
51 | * `-c, --clean`: Clean the output directory first
52 |
53 | * `-v, --verbose`: Enables verbose diagnostics
54 |
55 | * `-q, --quiet`: Turns off all output
56 |
57 | * `-h, --help`: Print help
58 |
--------------------------------------------------------------------------------
/docs/guide/commands/config.md:
--------------------------------------------------------------------------------
1 | # `config`
2 |
3 | Reads or modifies the global `config.toml` file.
4 |
5 | The config file can be read via `--get` and it can be set with one of the set options (`--set`, `--set-int`,
6 | `--set-bool`, or `--unset`). Each of the set operations takes a key=value pair. All of these can be supplied
7 | multiple times.
8 |
9 | ## Example
10 |
11 | This command turns on global shims:
12 |
13 | ```
14 | rye config --set-bool behavior.global-python=true
15 | ```
16 |
17 | Reads the currently set config value for global Python shims:
18 |
19 | ```
20 | $ rye config --get behavior.global-python
21 | true
22 | ```
23 |
24 | Show the path to the config:
25 |
26 | ```
27 | $ rye config --show-path
28 | /Users/username/.rye/config.toml
29 | ```
30 |
31 | ## Arguments
32 |
33 | *no arguments*
34 |
35 | ## Options
36 |
37 | * `--get `: Reads a config key
38 |
39 | * `--set `: Sets a config key to a string
40 |
41 | * `--set-int `: Sets a config key to an integer
42 |
43 | * `--set-bool `: Sets a config key to a bool
44 |
45 | * `--unset `: Remove a config key
46 |
47 | * `--show-path`: Print the path to the config
48 |
49 | * `--format `: Request parseable output format rather than lines
50 |
51 | [possible values: json]
52 |
53 | * `-h, --help`: Print help (see a summary with '-h')
--------------------------------------------------------------------------------
/docs/guide/commands/fetch.md:
--------------------------------------------------------------------------------
1 | # `fetch`
2 |
3 | Fetches a Python interpreter for the local machine. This command is
4 | available under the aliases `rye fetch` and `rye toolchain fetch`.
5 |
6 | As of Rye 0.31.0 toolchains are always fetched without build info. This
7 | means that in the folder where toolchains are stored only the interpreter
8 | is found. For more information see [Fetching Toolchains](../toolchains/index.md#build-info).
9 |
10 | ## Example
11 |
12 | Fetch a specific version of Python:
13 |
14 | ```
15 | $ rye fetch 3.8.13
16 | Downloading cpython@3.8.13
17 | Checking checksum
18 | Unpacking
19 | Downloaded cpython@3.8.13
20 | ```
21 |
22 | To fetch the pinned version of Python you can leave out the argument:
23 |
24 | ```
25 | $ rye fetch
26 | Downloading cpython@3.8.17
27 | Checking checksum
28 | Unpacking
29 | Downloaded cpython@3.8.17
30 | ```
31 |
32 | To fetch a version of Python into a specific location rather than rye's
33 | interpreter cache:
34 |
35 | ```
36 | $ rye fetch cpython@3.9.1 --target-path=my-interpreter
37 | ```
38 |
39 | ## Arguments
40 |
41 | * `[VERSION]`: The version of Python to fetch.
42 |
43 | If no version is provided, the requested version will be fetched.
44 |
45 | ## Options
46 |
47 | * `-f, --force`: Fetch the Python toolchain even if it is already installed.
48 |
49 | * `--target-path` ``: Fetches the Python toolchain into an explicit location rather
50 |
51 | * `--build-info`: Fetches with build info
52 |
53 | * `--no-build-info`: Fetches without build info
54 |
55 | * `-v, --verbose`: Enables verbose diagnostics
56 |
57 | * `-q, --quiet`: Turns off all output
58 |
59 | * `-h, --help`: Print help (see a summary with '-h')
--------------------------------------------------------------------------------
/docs/guide/commands/fmt.md:
--------------------------------------------------------------------------------
1 | # `fmt`
2 |
3 | +++ 0.20.0
4 |
5 | Run the code formatter on the project. This command is aliased to `format`.
6 |
7 | For more information about how to configure Ruff, have a look at the
8 | [Ruff Configuration Documentation](https://docs.astral.sh/ruff/configuration/).
9 |
10 | ## Example
11 |
12 | To format the code and write back to the files:
13 |
14 | ```
15 | $ rye fmt
16 | 1 file reformatted, 231 files left unchanged
17 | ```
18 |
19 | To just check if the code needs formatting:
20 |
21 | ```
22 | $ rye fmt --check
23 | Would reformat: src/my_project/utils.py
24 | 1 file would be reformatted, 231 files already formatted
25 | ```
26 |
27 | To pass extra arguments to the underlying `ruff` formatter use `--`:
28 |
29 | ```
30 | $ rye fmt -- --diff
31 | --- src/my_project/utils.py
32 | +++ src/my_project/utils.py
33 | @@ -2,5 +2,4 @@
34 |
35 |
36 | def foo():
37 | -
38 | pass
39 |
40 | 1 file would be reformatted, 231 files already formatted
41 | ```
42 |
43 | Format a specific file:
44 |
45 | ```
46 | rye fmt src/foo.py
47 | ```
48 |
49 | ## Arguments
50 |
51 | * `[PATHS]...` List of files or directories to lint. If not supplied all files are formatted.
52 |
53 | * `[EXTRA_ARGS]...` Extra arguments to the formatter.
54 |
55 | These arguments are forwarded directly to the underlying formatter (currently
56 | always `ruff`). Note that extra arguments must be separated from other arguments
57 | with the `--` marker.
58 |
59 | ## Options
60 |
61 | * `-a, --all`: Format all packages in the workspace
62 |
63 | * `-p, --package `: Format a specific package
64 |
65 | * `--pyproject `: Use this `pyproject.toml` file
66 |
67 | * `--check`: Run format in check mode
68 |
69 | * `-v, --verbose`: Enables verbose diagnostics
70 |
71 | * `-q, --quiet`: Turns off all output
72 |
73 | * `-h, --help`: Print help (see a summary with '-h')
--------------------------------------------------------------------------------
/docs/guide/commands/index.md:
--------------------------------------------------------------------------------
1 | # Commands
2 |
3 | This is a list of all the commands that rye provides:
4 |
5 | * [add](add.md): Adds a Python package to this project
6 | * [build](build.md): Builds a package for distribution
7 | * [config](config.md): Reads or updates the Rye configuration
8 | * [fetch](fetch.md): Fetches a Python interpreter for the local machine (alias)
9 | * [fmt](fmt.md): Run the code formatter on the project
10 | * [init](init.md): Initializes a new project
11 | * [install](install.md): Installs a global tool (alias)
12 | * [lock](lock.md): Updates the lockfiles without installing dependencies
13 | * [lint](lint.md): Run the linter on the project
14 | * [make-req](make-req.md): Builds and prints a PEP 508 requirement string from parts
15 | * [pin](pin.md): Pins a Python version to the project
16 | * [publish](publish.md): Publish packages to a package repository
17 | * [remove](remove.md): Remove a dependency from this project
18 | * [run](run.md): Runs a command installed into this package
19 | * [show](show.md): Prints the current state of the project
20 | * [sync](sync.md): Updates the virtualenv based on the pyproject.toml
21 | * [test](test.md): Runs the project's tests
22 | * [toolchain](toolchain/index.md): Helper utility to manage Python toolchains
23 | * [tools](tools/index.md): Helper utility to manage global tools.
24 | * [self](self/index.md): Rye self management
25 | * [uninstall](uninstall.md): Uninstalls a global tool (alias)
26 | * [version](version.md): Get or set project version
27 |
28 | ## Options
29 |
30 | The toplevel `rye` command accepts the following options:
31 |
32 | * `--env-file` ``: This can be supplied multiple times to make rye load
33 | a given `.env` file. Note that this file is not referenced to handle the
34 | `RYE_HOME` variable which must be supplied as environment variable always.
--------------------------------------------------------------------------------
/docs/guide/commands/init.md:
--------------------------------------------------------------------------------
1 | # `init`
2 |
3 | This command initializes a new or existing Python project with Rye. Running it in
4 | a folder with an already existing Python project will attempt to convert it over
5 | and bootstrap Rye right there. Otherwise it can be used to create a completely new
6 | project from scratch.
7 |
8 | For more information see the [Basics Guide](../basics.md).
9 |
10 | ## Example
11 |
12 | ```
13 | $ rye init
14 | success: Initialized project in /Users/john/Development/my-project.
15 | Run `rye sync` to get started
16 | ```
17 |
18 | ## Arguments
19 |
20 | * `[PATH]`: Where to place the project (defaults to current path)
21 |
22 | ## Options
23 |
24 | * `--min-py `: Minimal Python version supported by this project
25 |
26 | * `-p, --py `: Python version to use for the virtualenv
27 |
28 | * `--no-readme`: Do not create a readme
29 |
30 | * `--no-pin`: Do not create .python-version file (requires-python will be used)
31 |
32 | * `--build-system `: Which build system should be used(defaults to hatchling)?
33 |
34 | [possible values: `hatchling`, `setuptools`, `flit`, `pdm`, `maturin`]
35 |
36 | * `--license `: Which license should be used? [SPDX identifier](https://spdx.org/licenses/)
37 |
38 | * `--name `: The name of the package
39 |
40 | * `--private`: Set "Private :: Do Not Upload" classifier, used for private projects
41 |
42 | * `--no-import`: Don't import from setup.cfg, setup.py, or requirements files
43 |
44 | * `--virtual`: Initialize this as a virtual package.
45 |
46 | A virtual package can have dependencies but is itself not installed as a Python package. It also cannot be published.
47 |
48 | * `-r, --requirements `: Requirements files to initialize pyproject.toml with
49 |
50 | * `--dev-requirements `: Development requirements files to initialize pyproject.toml with
51 |
52 | * `-v, --verbose`: Enables verbose diagnostics
53 |
54 | * `-q, --quiet`: Turns off all output
55 |
56 | * `-h, --help`: Print help (see a summary with '-h')
57 |
--------------------------------------------------------------------------------
/docs/guide/commands/install.md:
--------------------------------------------------------------------------------
1 | # `install`
2 |
3 | Installs a package as global tool. This command has two names
4 | to `rye tools install` and `rye install`.
5 |
6 | This can be used to install useful Python scripts globally into it's own
7 | separated virtualenv. For instance if you want to use the `black` formatter
8 | you can install it once.
9 |
10 | Normally only scripts installed by the top level dependency are installed. In
11 | some cases you might also want to install commands from sub-dependencies. In
12 | that case pass those dependencies with `--include-dep`.
13 |
14 | For more information see [Tools](/guide/tools/).
15 |
16 | ## Example
17 |
18 | ```
19 | $ rye tools install pycowsay
20 | Looking in indexes: https://pypi.org/simple/
21 | Collecting pycowsay
22 | Downloading pycowsay-0.0.0.2-py3-none-any.whl.metadata (965 bytes)
23 | Downloading pycowsay-0.0.0.2-py3-none-any.whl (4.0 kB)
24 | Installing collected packages: pycowsay
25 | Successfully installed pycowsay-0.0.0.2
26 |
27 | Installed scripts:
28 | - pycowsay
29 |
30 | $ pycowsay "Great Stuff"
31 |
32 | -----------
33 | < Great Stuff >
34 | -----------
35 | \ ^__^
36 | \ (oo)\_______
37 | (__)\ )\/\
38 | ||----w |
39 | || ||
40 | ```
41 |
42 | ## Arguments
43 |
44 | * `...`: The package to install as PEP 508 requirement string.
45 |
46 | ## Options
47 |
48 | * `--git `: Install the given package from this git repository
49 |
50 | * `--url `: Install the given package from this URL
51 |
52 | * `--path `: Install the given package from this local path
53 |
54 | * `--absolute`: Force non interpolated absolute paths
55 |
56 | * `--tag `: Install a specific tag
57 |
58 | * `--rev `: Update to a specific git rev
59 |
60 | * `--branch `: Update to a specific git branch
61 |
62 | * `--features `: Adds a dependency with a specific feature
63 |
64 | * `--include-dep `: Include scripts from a given dependency
65 |
66 | * `--extra-requirement `: Additional dependencies to install that are not declared by the main package
67 |
68 | * `-p, --python `: Optionally the Python version to use
69 |
70 | * `-f, --force`: Force install the package even if it's already there
71 |
72 | * `-v, --verbose`: Enables verbose diagnostics
73 |
74 | * `-q, --quiet`: Turns off all output
75 |
76 | * `-h, --help`: Print help (see a summary with '-h')
--------------------------------------------------------------------------------
/docs/guide/commands/lint.md:
--------------------------------------------------------------------------------
1 | # `lint`
2 |
3 | +++ 0.20.0
4 |
5 | Run the linter on the project. This command is aliased to `check`. At the moment
6 | this always runs `ruff` in lint mode.
7 |
8 | For more information about how to configure Ruff, have a look at the
9 | [Ruff Configuration Documentation](https://docs.astral.sh/ruff/configuration/).
10 |
11 | ## Example
12 |
13 | Run the linter:
14 |
15 | ```
16 | $ rye lint
17 | src/myproject/sdk.py:1:8: F401 [*] `sys` imported but unused
18 | Found 1 error.
19 | [*] 1 fixable with the `--fix` option.
20 | ```
21 |
22 | For issues that can be auto fixed pass `--fix`:
23 |
24 | ```
25 | $ rye lint --fix
26 | Found 1 error (1 fixed, 0 remaining).
27 | ```
28 |
29 | To pass extra arguments:
30 |
31 | ```
32 | $ rye lint -- --watch
33 | ```
34 |
35 | Lint a specific file:
36 |
37 | ```
38 | rye lint src/foo.py
39 | ```
40 |
41 | ## Arguments
42 |
43 | * `[PATHS]...` List of files or directories to lint. If not supplied all files are linted.
44 |
45 | * `[EXTRA_ARGS]...` Extra arguments to the linter.
46 |
47 | These arguments are forwarded directly to the underlying linter (currently
48 | always `ruff`). Note that extra arguments must be separated from other arguments
49 | with the `--` marker.
50 |
51 | ## Options
52 |
53 | * `-a, --all`: Lint all packages in the workspace
54 |
55 | * `-p, --package `: Format a specific package
56 |
57 | * `--pyproject `: Use this `pyproject.toml` file
58 |
59 | * `--fix`: Automatically fix fixable issues
60 |
61 | * `-v, --verbose`: Enables verbose diagnostics
62 |
63 | * `-q, --quiet`: Turns off all output
64 |
65 | * `-h, --help`: Print help (see a summary with '-h')
--------------------------------------------------------------------------------
/docs/guide/commands/list.md:
--------------------------------------------------------------------------------
1 | # `list`
2 |
3 | +++ 0.24.0
4 |
5 | Prints a list of installed dependencies.
6 |
7 | ## Example
8 |
9 | ```
10 | $ rye list
11 | asgiref==3.7.2
12 | blinker==1.7.0
13 | click==8.1.7
14 | Flask @ git+https://github.com/pallets/flask@4df377cfbfc1d15e962a61c18920b22aebc9aa41
15 | itsdangerous==2.1.2
16 | Jinja2==3.1.3
17 | MarkupSafe==2.1.4
18 | Werkzeug==3.0.1
19 | ```
20 |
21 | ## Arguments
22 |
23 | *no arguments*
24 |
25 | ## Options
26 |
27 | * `--pyproject`: Use this `pyproject.toml` file
28 |
29 | * `-h, --help`: Print help (see a summary with '-h')
--------------------------------------------------------------------------------
/docs/guide/commands/lock.md:
--------------------------------------------------------------------------------
1 | # `lock`
2 |
3 | Updates the lockfiles without installing dependencies. Usually one would use
4 | the [`sync`](sync.md) command instead which both locks and installs dependencies.
5 |
6 | For more information see [Syncing and Locking](../sync.md).
7 |
8 | ## Example
9 |
10 | ```
11 | $ rye lock
12 | Generating production lockfile: /Users/username/my-project/requirements.lock
13 | Generating dev lockfile: /Users/username/my-project/requirements-dev.lock
14 | Done!
15 | ```
16 |
17 | ## Arguments
18 |
19 | *no arguments*
20 |
21 | ## Options
22 |
23 | * `--update `: Update a specific package
24 |
25 | * `--update-all`: Update all packages to the latest
26 |
27 | * `--pre`: Update to pre-release versions
28 |
29 | * `--features `: Extras/features to enable when locking the workspace
30 |
31 | * `--all-features`: Enables all features
32 |
33 | * `--generate-hashes`: Set to true to lock with hashes in the lockfile
34 |
35 | * `--with-sources`: Set to true to lock with sources in the lockfile
36 |
37 | * `--pyproject `: Use this pyproject.toml file
38 |
39 | * `-v, --verbose`: Enables verbose diagnostics
40 |
41 | * `-q, --quiet`: Turns off all output
42 |
43 | * `-h, --help`: Print help (see a summary with '-h')
--------------------------------------------------------------------------------
/docs/guide/commands/make-req.md:
--------------------------------------------------------------------------------
1 | # `make-req`
2 |
3 | Builds and prints a PEP 508 requirement string from parts. This is a utility command
4 | that rarely needs to be used but can help creating requirements strings for pasting into
5 | other tools. It takes the same arguments as [`add`](add.md) but rather than adding the
6 | requirements into the requirements file it just spits out a formatted PEP 508 requirement
7 | string on stdout.
8 |
9 | ## Example
10 |
11 | ```
12 | $ rye make-req flask --git https://github.com/pallets/flask --rev 4df377cfbf
13 | flask @ git+https://github.com/pallets/flask@4df377cfbf
14 | ```
15 |
16 | ## Arguments
17 |
18 | * `[REQUIREMENTS]...` The package to add as PEP 508 requirement string. e.g. `'flask==2.2.3'`
19 |
20 | ## Options
21 |
22 | * `--git `: Install the given package from this git repository
23 |
24 | * `--url `: Install the given package from this URL
25 |
26 | * `--path `: Install the given package from this local path
27 |
28 | * `--absolute`: Force non interpolated absolute paths
29 |
30 | * `--tag `: Install a specific tag
31 |
32 | * `--rev `: Update to a specific git rev
33 |
34 | * `--branch `: Update to a specific git branch
35 |
36 | * `--features `: Adds a dependency with a specific feature
37 |
38 | * `-h, --help`: Print help (see a summary with '-h')
--------------------------------------------------------------------------------
/docs/guide/commands/pin.md:
--------------------------------------------------------------------------------
1 | # `pin`
2 |
3 | Pins a Python version to this project.
4 |
5 | This will update the `.python-version` to point to the provided version.
6 | Additionally it will update `requires-python` in the `pyproject.toml` if it's
7 | lower than the current version. This can be disabled by passing
8 | `--no-update-requires-python`.
9 |
10 | Which toolchain Rye prefers depends on the Rye version. From 0.22 onwards
11 | the latest compatible installed toolchain is picked, and only if a non
12 | existing one is found a download will be attempted. For older versions
13 | Rye will always attempt to download the latest available if it's not
14 | installed yet unless a precise pin is selected.
15 |
16 | ## Example
17 |
18 | Pin a specific version of Python:
19 |
20 | ```
21 | $ rye pin 3.9
22 | pinned 3.9.18 in /Users/username/my-project
23 | ```
24 |
25 | To issue a relaxed and not a specific pin use `--relaxed`:
26 |
27 | ```
28 | $ rye pin 3.9 --relaxed
29 | pinned 3.9 in /Users/username/my-project
30 | ```
31 |
32 | ## Arguments
33 |
34 | * ``: The version of Python to pin
35 |
36 | This can be a short version (3.9) or a full one (`cpython@3.9.18`).
37 |
38 | ## Options
39 |
40 | * `--relaxed`: Issue a relaxed pin
41 |
42 | * `--no-update-requires-python`: Prevent updating requires-python in the `pyproject.toml`
43 |
44 | * `--pyproject `: Use this `pyproject.toml` file
45 |
46 | * `-h, --help`: Print help (see a summary with '-h')
--------------------------------------------------------------------------------
/docs/guide/commands/publish.md:
--------------------------------------------------------------------------------
1 | # `publish`
2 |
3 | Publish packages to a package repository. This publishes the packages which are
4 | produced by the build command.
5 |
6 | For more information see [Building and Publishing](../publish.md).
7 |
8 | ## Example
9 |
10 | Build and publish:
11 |
12 | ```
13 | $ rye build
14 | $ rye publish
15 | ```
16 |
17 | Publish a specific artifact:
18 |
19 | ```
20 | $ rye publish dist/example-0.1.0.tar.gz
21 | ```
22 |
23 | ## Arguments
24 |
25 | * `[DIST]...`: The distribution files to upload to the repository (defaults to `/dist/*`)
26 |
27 | ## Options
28 |
29 | * `-r, --repository `: The repository to publish to [default: `pypi`]
30 |
31 | * `--repository-url `: The repository url to publish to
32 |
33 | * `-u, --username `: The username to authenticate to the repository with
34 |
35 | * `--token `: An access token used for the upload
36 |
37 | * `--sign`: Sign files to upload using GPG
38 |
39 | * `-i, --identity `: GPG identity used to sign files
40 |
41 | * `--cert `: Path to alternate CA bundle
42 |
43 | * `--skip-existing`: Skip files already published (repository must support this feature)
44 |
45 | * `-y, --yes`: Skip prompts
46 |
47 | * `-v, --verbose`: Enables verbose diagnostics
48 |
49 | * `-q, --quiet`: Turns off all output
50 |
51 | * `-h, --help`: Print help (see a summary with '-h')
--------------------------------------------------------------------------------
/docs/guide/commands/remove.md:
--------------------------------------------------------------------------------
1 | # `remove`
2 |
3 | Removes a package from this project. This removes a package from the `pyproject.toml`
4 | dependency list.
5 |
6 | If auto sync is disabled, after a dependency is removed it's not automatically
7 | uninstalled. To do that, you need to invoke the [`sync`](sync.md) command or pass
8 | `--sync`.
9 |
10 | +++ 0.26.0
11 |
12 | Added support for auto-sync and the `--sync` / `--no-sync` flags.
13 |
14 | ## Example
15 |
16 | ```
17 | $ rye remove flask
18 | Removed flask>=3.0.1
19 | ```
20 |
21 | ## Arguments
22 |
23 | * `...`: The packages to remove from the project
24 |
25 | ## Options
26 |
27 | * `--dev`: Remove this from dev dependencies
28 |
29 | * `--optional `: Remove this from the optional dependency group
30 |
31 | * `--sync`: Runs `sync` automatically even if auto-sync is disabled.
32 |
33 | * `--no-sync`: Does not run `sync` automatically even if auto-sync is enabled.
34 |
35 | * `-v, --verbose`: Enables verbose diagnostics
36 |
37 | * `-q, --quiet`: Turns off all output
38 |
39 | * `-h, --help`: Print help (see a summary with '-h')
--------------------------------------------------------------------------------
/docs/guide/commands/run.md:
--------------------------------------------------------------------------------
1 | # `run`
2 |
3 | Runs a command installed into this package. This either runs a script or application
4 | made available in the virtualenv or a Rye specific script.
5 |
6 | For more information see [`rye.tool.scripts`](../pyproject.md#toolryescripts).
7 |
8 | ## Example
9 |
10 | Run a tool from the virtualenv:
11 |
12 | ```
13 | $ rye run flask
14 | ```
15 |
16 | Invoke it without arguments to see all available scripts:
17 |
18 | ```
19 | $ rye run
20 | flask
21 | hello
22 | python
23 | python3
24 | python3.9
25 | ```
26 |
27 | ## Arguments
28 |
29 | * `[COMMAND]`: The name of the command and the arguments to it.
30 |
31 | ## Options
32 |
33 | * `-l, --list`: List all commands (implied without arguments)
34 |
35 | * `--pyproject`: Use this `pyproject.toml` file
36 |
37 | * `-h, --help`: Print help (see a summary with '-h')
--------------------------------------------------------------------------------
/docs/guide/commands/self/completion.md:
--------------------------------------------------------------------------------
1 | # `completion`
2 |
3 | Generates a completion script for a shell
4 |
5 | ## Example
6 |
7 | Generate a completion script for zsh and load it:
8 |
9 | ```
10 | $ eval "$(rye self completion -s zsh)"
11 | ```
12 |
13 | ## Arguments
14 |
15 | _no arguments_
16 |
17 | ## Options
18 |
19 | * `-s, --shell `: The shell to generate a completion script for (defaults to 'bash')
20 |
21 | [possible values: `bash`, `elvish`, `fish`, `powershell`, `zsh`, `nushell`]
22 |
23 | * `-h, --help`: Print help (see a summary with '-h')
24 |
--------------------------------------------------------------------------------
/docs/guide/commands/self/index.md:
--------------------------------------------------------------------------------
1 | # `self`
2 |
3 | Command to manage Rye itself.
4 |
5 | * [`completion`](completion.md): Generates a completion script for Rye.
6 |
7 | * [`update`](update.md): Performs an update of Rye.
8 |
9 | * [`uninstall`](uninstall.md): Uninstalls Rye again.
10 |
--------------------------------------------------------------------------------
/docs/guide/commands/self/uninstall.md:
--------------------------------------------------------------------------------
1 | # `uninstall`
2 |
3 | Uninstalls rye again. Note that this leaves a trace
4 | `.rye` folder behind with an empty `env` file. You also
5 | need to remove the sourcing of that script from your
6 | `.profile` file.
7 |
8 | ## Example
9 |
10 | Uninstall rye without asking:
11 |
12 | ```
13 | $ rye self uninstall --yes
14 | ```
15 |
16 | ## Arguments
17 |
18 | _no arguments_
19 |
20 | ## Options
21 |
22 | * `-y, --yes`: Do not prompt and uninstall.
23 |
24 | * `-h, --help`: Print help (see a summary with '-h')
25 |
--------------------------------------------------------------------------------
/docs/guide/commands/self/update.md:
--------------------------------------------------------------------------------
1 | # `update`
2 |
3 | Performs an update of rye.
4 |
5 | This can install updates from the latest release binaries or trigger a manual
6 | compilation of Rye if Rust is installed.
7 |
8 | ## Example
9 |
10 | Update to the latest version:
11 |
12 | ```
13 | $ rye self update
14 | ```
15 |
16 | Update (or downgrade) to a specific version:
17 |
18 | ```
19 | $ rye self update --version 0.20
20 | ```
21 |
22 | Compile a specific revision:
23 |
24 | ```
25 | $ rye self update --rev 08910bc9b3b7c72a3d3ac694c4f3412259161477
26 | ```
27 |
28 | Compile latest development version:
29 |
30 | ```
31 | $ rye self update --branch main
32 | ```
33 |
34 | ## Arguments
35 |
36 | _no arguments_
37 |
38 | ## Options
39 |
40 | * `--version `: Update to a specific version
41 |
42 | * `--tag `: Update to a specific tag
43 |
44 | * `--rev `: Update to a specific git rev
45 |
46 | * `--branch `: Update to a specific git branch
47 |
48 | * `--force`: Force reinstallation
49 |
50 | * `-h, --help`: Print help (see a summary with '-h')
51 |
--------------------------------------------------------------------------------
/docs/guide/commands/show.md:
--------------------------------------------------------------------------------
1 | # `show`
2 |
3 | Prints the current state of the project. This can print out information about the
4 | virtualenv, the project or workspace as well as a list of installed dependencies.
5 |
6 | ## Example
7 |
8 | Print out the status of a project:
9 |
10 | ```
11 | $ rye show
12 | project: my-project
13 | path: /Users/username/my-project
14 | venv: /Users/username/my-project/.venv
15 | target python: 3.8
16 | venv python: cpython@3.9.18
17 | virtual: false
18 | ```
19 |
20 | ## Arguments
21 |
22 | *no arguments*
23 |
24 | ## Options
25 |
26 | * `--installed-deps`: Print the currently installed dependencies.
27 |
28 | This option is being replaced with [`rye list`](list.md)
29 |
30 | * `--pyproject`: Use this `pyproject.toml` file
31 |
32 | * `-h, --help`: Print help (see a summary with '-h')
--------------------------------------------------------------------------------
/docs/guide/commands/sync.md:
--------------------------------------------------------------------------------
1 | # `sync`
2 |
3 | Updates the lockfiles and installs the dependencies into the virtualenv.
4 |
5 | For more information see [Syncing and Locking](../sync.md).
6 |
7 | ## Example
8 |
9 | Sync the project:
10 |
11 | ```
12 | $ rye sync
13 | Reusing already existing virtualenv
14 | Generating production lockfile: /Users/username/my-project/requirements.lock
15 | Generating dev lockfile: /Users/username/my-project/requirements-dev.lock
16 | Installing dependencies
17 | ...
18 | ```
19 |
20 | To sync without updating the lock file use `--no-lock`:
21 |
22 | ```
23 | $ rye sync --no-lock
24 | ```
25 |
26 | If you do not want dev dependencies to be installed use `--no-dev`:
27 |
28 | ```
29 | $ rye sync --no-dev
30 | ```
31 |
32 | To exit the sub shell run `exit`.
33 |
34 | ## Arguments
35 |
36 | *no arguments*
37 |
38 | ## Options
39 |
40 | * `-f, --force`: Force the virtualenv to be re-created
41 |
42 | * `--no-dev`: Do not install dev dependencies
43 |
44 | * `--no-lock`: Do not update the lockfile.
45 |
46 | * `--update `: Update a specific package
47 |
48 | * `--update-all`: Update all packages to the latest
49 |
50 | * `--pre`: Update to pre-release versions
51 |
52 | * `--features `: Extras/features to enable when locking the workspace
53 |
54 | * `--all-features`: Enables all features
55 |
56 | * `--generate-hashes`: Set to true to lock with hashes in the lockfile
57 |
58 | * `--with-sources`: Set to true to lock with sources in the lockfile
59 |
60 | * `--pyproject `: Use this pyproject.toml file
61 |
62 | * `-v, --verbose`: Enables verbose diagnostics
63 |
64 | * `-q, --quiet`: Turns off all output
65 |
66 | * `-h, --help`: Print help (see a summary with '-h')
67 |
--------------------------------------------------------------------------------
/docs/guide/commands/test.md:
--------------------------------------------------------------------------------
1 | # `test`
2 |
3 | +++ 0.28.0
4 |
5 | Run the test suites of the project. At the moment this always runs `pytest`.
6 | Note that `pytest` must be installed into the virtual env unlike `ruff`
7 | which is used behind the scenes automatically for linting and formatting.
8 | Thus in order to use this, you need to declare `pytest` as dev dependency.
9 |
10 | ```
11 | $ rye add --dev pytest
12 | ```
13 |
14 | It's recommended to place tests in a folder called `tests` adjacent to the
15 | `src` folder of your project.
16 |
17 | For more information about how to use pytest, have a look at the
18 | [Pytest Documentation](https://docs.pytest.org/en/8.0.x/).
19 |
20 | ## Example
21 |
22 | Run the test suite:
23 |
24 | ```
25 | $ rye test
26 | platform win32 -- Python 3.11.1, pytest-8.0.2, pluggy-1.4.0
27 | rootdir: /Users/john/Development/stuff
28 | plugins: anyio-4.3.0
29 | collected 1 item
30 |
31 | stuff/tests/test_batch.py . [100%]
32 | ```
33 |
34 | ## Arguments
35 |
36 | * `[EXTRA_ARGS]...` Extra arguments to the test runner.
37 |
38 | These arguments are forwarded directly to the underlying test runner (currently
39 | always `pytest`). Note that extra arguments must be separated from other arguments
40 | with the `--` marker.
41 |
42 | ## Options
43 |
44 | * `-a, --all`: Test all packages in the workspace
45 |
46 | * `-p, --package `: Run the test suite of a specific package
47 |
48 | * `--pyproject `: Use this `pyproject.toml` file
49 |
50 | * `-v, --verbose`: Enables verbose diagnostics
51 |
52 | * `-q, --quiet`: Turns off all output
53 |
54 | * `-i, --ignore`: Ignore the specified directory
55 |
56 | * `-s`, `--no-capture`: Disable stdout/stderr capture for the test runner
57 |
58 | * `-h, --help`: Print help (see a summary with '-h')
59 |
--------------------------------------------------------------------------------
/docs/guide/commands/toolchain/fetch.md:
--------------------------------------------------------------------------------
1 | ../fetch.md
--------------------------------------------------------------------------------
/docs/guide/commands/toolchain/index.md:
--------------------------------------------------------------------------------
1 | # `toolchain`
2 |
3 | Helper utility to manage Python toolchains. The following subcommands exist:
4 |
5 | * [`fetch`](fetch.md): fetches a toolchain
6 |
7 | * [`list`](list.md): lists all registered toolchains
8 |
9 | * [`register`](register.md): register a Python binary as custom toolchain
10 |
11 | * [`remove`](remove.md): removes or uninstalls a toolchain
--------------------------------------------------------------------------------
/docs/guide/commands/toolchain/list.md:
--------------------------------------------------------------------------------
1 | # `list`
2 |
3 | List all registered toolchains. It can list the toolchains which are installed as
4 | well as toolchains which can be downloaded if `--include-downloadable` is passed.
5 |
6 | ## Example
7 |
8 | List installed toolchains:
9 |
10 | ```
11 | $ rye toolchain list
12 | cpython@3.12.1 (/Users/username/.rye/py/cpython@3.12.1/install/bin/python3)
13 | cpython@3.11.6 (/Users/username/.rye/py/cpython@3.11.6/install/bin/python3)
14 | ```
15 |
16 | Lists downloadable toolchains:
17 |
18 | ```
19 | $ rye toolchain list --include-downloadable
20 | cpython@3.12.1 (/Users/mitsuhiko/.rye/py/cpython@3.12.1/install/bin/python3)
21 | cpython-x86_64@3.12.1 (downloadable)
22 | cpython@3.11.7 (downloadable)
23 | ...
24 | ```
25 |
26 | ## Arguments
27 |
28 | *no arguments*
29 |
30 | ## Options
31 |
32 | * `--include-downloadable`: Also include non installed, but downloadable toolchains
33 |
34 | * `--format `: Request parseable output format [possible values: json]
35 |
36 | * `-h, --help`: Print help
37 |
--------------------------------------------------------------------------------
/docs/guide/commands/toolchain/register.md:
--------------------------------------------------------------------------------
1 | # `register`
2 |
3 | Register a Python binary as custom toolchain.
4 |
5 | Rye by default will automatically download Python releases from the internet.
6 | However it's also possible to register already available local Python
7 | installations. This allows you to use rye with self compiled Pythons.
8 |
9 | The name of the toolchain is auto detected (eg: `cpython`, `pypy` etc.)
10 |
11 | To unregister use the [`remove`](remove.md) command.
12 |
13 | ## Example
14 |
15 | ```
16 | $ rye toolchain register /opt/homebrew/Cellar/python@3.10/3.10.6_1/bin/python3.10
17 | Registered /opt/homebrew/Cellar/python@3.10/3.10.6_1/bin/python3.10 as cpython@3.10.6
18 | ```
19 |
20 | ## Arguments
21 |
22 | * ``: Path to the python binary that should be registered
23 |
24 | ## Options
25 |
26 | * `-n, --name `: Name of the toolchain. If not provided a name is auto detected.
27 |
28 | * `-h, --help`: Print help (see a summary with '-h')
--------------------------------------------------------------------------------
/docs/guide/commands/toolchain/remove.md:
--------------------------------------------------------------------------------
1 | # `remove`
2 |
3 | Removes or uninstalls a toolchain.
4 |
5 | ## Example
6 |
7 | ```
8 | $ rye toolchain remove 3.9.5
9 | Removed installed toolchain cpython@3.9.5
10 | ```
11 |
12 | ## Arguments
13 |
14 | * `` The version of Python to remove.
15 |
16 | ## Options
17 |
18 | * `-f, --force`: Force removal even if the toolchain is in use
19 | * `-h, --help`: Print help (see a summary with '-h')
--------------------------------------------------------------------------------
/docs/guide/commands/tools/index.md:
--------------------------------------------------------------------------------
1 | # `tools`
2 |
3 | Helper utility to manage global tool installations.
4 |
5 | * [`install`](install.md): installs a tool globally.
6 |
7 | * [`uninstall`](uninstall.md): uninstalls a globally installed tool.
8 |
9 | * [`list`](list.md): lists all globally installed tools.
10 |
--------------------------------------------------------------------------------
/docs/guide/commands/tools/install.md:
--------------------------------------------------------------------------------
1 | ../install.md
--------------------------------------------------------------------------------
/docs/guide/commands/tools/list.md:
--------------------------------------------------------------------------------
1 | # `list`
2 |
3 | Lists all already installed global tools.
4 |
5 | For more information see [Tools](/guide/tools/).
6 |
7 | ## Example
8 |
9 | List installed tools:
10 |
11 | ```
12 | $ rye tools list
13 | pycowsay
14 | ```
15 |
16 | List installed tools with version:
17 |
18 | ```
19 | $ rye tools list --include-version
20 | pycowsay 0.0.0.2 (cpython@3.12.1)
21 | ```
22 |
23 | ## Arguments
24 |
25 | *no arguments*
26 |
27 | ## Options
28 |
29 | * `-s, --include-scripts`: Show all the scripts installed by the tools
30 |
31 | +/- 0.26.0
32 |
33 | Renamed from `-i, --include-scripts` to `-s, --include-scripts`.
34 |
35 | * `-v, --include-version`: Show the version of tools
36 |
37 | +/- 0.26.0
38 |
39 | Renamed from `-v, --version-show` to `-v, --include-version`.
40 |
41 | * `-h, --help`: Print help
42 |
--------------------------------------------------------------------------------
/docs/guide/commands/tools/uninstall.md:
--------------------------------------------------------------------------------
1 | ../uninstall.md
--------------------------------------------------------------------------------
/docs/guide/commands/uninstall.md:
--------------------------------------------------------------------------------
1 | # `uninstall`
2 |
3 | Uninstalls an already installed global tool. This command has two names
4 | to `rye tools uninstall` and `rye uninstall`.
5 |
6 | For more information see [Tools](/guide/tools/).
7 |
8 | ## Example
9 |
10 | ```
11 | $ rye tools uninstall pycowsay
12 | Uninstalled pycowsay
13 | ```
14 |
15 | ## Arguments
16 |
17 | * ``: The package to uninstall.
18 |
19 | ## Options
20 |
21 | * `-v, --verbose`: Enables verbose diagnostics
22 |
23 | * `-q, --quiet`: Turns off all output
24 |
25 | * `-h, --help`: Print help (see a summary with '-h')
--------------------------------------------------------------------------------
/docs/guide/commands/version.md:
--------------------------------------------------------------------------------
1 | # `version`
2 |
3 | Get or set project version. Note that this does not refer to the version of Rye
4 | itself but the version that is set in the `pyproject.toml` file.
5 |
6 | ## Example
7 |
8 | Get the current version:
9 |
10 | ```
11 | $ rye version
12 | 0.1.0
13 | ```
14 |
15 | Bump the version by minor:
16 |
17 | ```
18 | $ rye version -b minor
19 | version bumped to 0.2.0
20 | ```
21 |
22 | Set to a specific version:
23 |
24 | ```
25 | $ rye version 1.0.0
26 | version set to 1.0.0
27 | ```
28 |
29 | ## Arguments
30 |
31 | * `[VERSION]`: the version to set
32 |
33 | ## Options
34 |
35 | * `-b, --bump `: automatically bump the version in a specific way (`major`, `minor` or `patch`)
36 |
37 | * `-h, --help`: Print help (see a summary with '-h')
--------------------------------------------------------------------------------
/docs/guide/config.md:
--------------------------------------------------------------------------------
1 | # Configuration
2 |
3 | Most of Rye's configuration is contained within the `pyproject.toml` file. There is however
4 | also a bit of global configuration to influence how it works.
5 |
6 | ## Changing Home Folder
7 |
8 | By default Rye places all its configuration in `~/.rye` on Unix and `%USERPROFILE%\.rye` on
9 | Windows. This behavior can be changed via the `RYE_HOME` environment variable. This is useful
10 | if you do not like the default location where Rye places its configuration or if you need
11 | to isolate it.
12 |
13 | ## Home Folder Structure
14 |
15 | The `.rye` home folder contains both user configuration as well as Rye-managed state such
16 | as [installed toolchains](toolchains/index.md). The following files and folders are placed within the
17 | `.rye` folder. Note that not all are always there.
18 |
19 | ### `config.toml`
20 |
21 | This is a configuration file that influences how Rye operates. Today very little configuration
22 | is available there. For the available config keys see [Config File](#config-file).
23 |
24 | ### `self`
25 |
26 | While Rye is written in Rust, it uses a lot of Python tools internally. These are maintained in
27 | an internal virtualenv stored in this location.
28 |
29 | ### `py`
30 |
31 | In this folder Rye stores the different [toolchains](toolchains/index.md). Normally those are folders
32 | containing downloaded Python distributions, but they can also be symlinks or special reference
33 | files.
34 |
35 | ### `shims`
36 |
37 | This folder contains shim binaries. These binaries are for instance the `python` executable
38 | which automatically proxies to the current virtualenv or globally installed [tools](tools.md).
39 |
40 | ## Config File
41 |
42 | The config file `config.toml` in the `.rye` folder today is only used to manage defaults. This
43 | is a fully annotated config file:
44 |
45 | ```toml
46 | [default]
47 | # This is the default value that is written into new pyproject.toml
48 | # files for the `project.requires-python` key
49 | requires-python = ">= 3.8"
50 |
51 | # This is the default toolchain that is used
52 | toolchain = "cpython@3.11.1"
53 |
54 | # This is the default build system that is used
55 | build-system = "hatchling"
56 |
57 | # This is the default license that is used
58 | license = "MIT"
59 |
60 | # This sets the default author (overrides the defaults from git). The
61 | # format here is "Name ".
62 | author = "Full Name "
63 |
64 | # The dependency operator to use by default for dependencies. The options are
65 | # '>=', '~=', and '=='. The default currently is '>='. This affects the behavior
66 | # of `rye add`.
67 | dependency-operator = ">="
68 |
69 | [proxy]
70 | # the proxy to use for HTTP (overridden by the http_proxy environment variable)
71 | http = "http://127.0.0.1:4000"
72 | # the proxy to use for HTTPS (overridden by the https_proxy environment variable)
73 | https = "http://127.0.0.1:4000"
74 |
75 | [behavior]
76 | # When set to `true` the `managed` flag is always assumed to be `true`.
77 | force-rye-managed = false
78 |
79 | # Enables global shims when set to `true`. This means that the installed
80 | # `python` shim will resolve to a Rye-managed toolchain even outside of
81 | # virtual environments.
82 | global-python = false
83 |
84 | # Enable or disable automatic `sync` after `add` and `remove`. This defaults
85 | # to `true` when uv is enabled and `false` otherwise.
86 | autosync = true
87 |
88 | # Marks the managed .venv in a way that cloud-based synchronization systems
89 | # like Dropbox and iCloud Files will not upload it. This defaults to `true`
90 | # as a .venv in cloud storage typically does not make sense. Set this to
91 | # `false` to disable this behavior.
92 | venv-mark-sync-ignore = true
93 |
94 | # When set to `true` Rye will fetch certain interpreters with build information.
95 | # This will increase the space requirements, will put the interpreter into an
96 | # extra folder called `./install/` and place build artifacts adjacent in `./build`.
97 | fetch-with-build-info = false
98 |
99 | # An array of tables with optional sources. Same format as in pyproject.toml
100 | [[sources]]
101 | name = "default"
102 | url = "https://pypi.org/simple/"
103 | ```
104 |
105 | ## Manipulating Config
106 |
107 | +++ 0.9.0
108 |
109 | The configuration can be read and modified with `rye config`. The
110 | keys are in dotted notation. `--get` reads a key, `--set`, `--set-int`,
111 | `--set-bool`, and `--unset` modify one.
112 |
113 | ```bash
114 | rye config --set proxy.http=http://127.0.0.1:4000
115 | rye config --set-bool behavior.force-rye-managed=true
116 | rye config --get default.requires-python
117 | ```
118 |
119 | For more information see [`config`](commands/config.md).
120 |
121 | ## Per Project Config
122 |
123 | For the project-specific `pyproject.toml` config see [pyproject.toml](pyproject.md).
124 |
--------------------------------------------------------------------------------
/docs/guide/deps.md:
--------------------------------------------------------------------------------
1 | # Dependencies
2 |
3 | Dependencies are declared in [pyproject.toml](pyproject.md) however adding them can be
4 | simplified with the [`rye add`](commands/add.md) command. In the most simple invocation it adds a regular
5 | dependency, but it can be customized.
6 |
7 | ## Adding Basic Dependency
8 |
9 | To add a regular dependency just invoke [`rye add`](commands/add.md) with the name of the Python package:
10 |
11 | ```
12 | rye add Flask
13 | ```
14 |
15 | If you also want to define a version, use a [PEP 508](https://peps.python.org/pep-0508/)
16 | requirement:
17 |
18 | ```
19 | rye add "Flask>=2.0"
20 | ```
21 |
22 | For extra/feature dependencies you can either use PEP 508 syntax or use `--features`:
23 |
24 | ```
25 | rye add "Flask[dotenv]"
26 | rye add Flask --features=dotenv
27 | ```
28 |
29 | These dependencies are stored in [`project.dependencies`](pyproject.md#projectdependencies).
30 |
31 | !!! tip "Note about pre-releases"
32 |
33 | By default `add` will not consider pre-releases. This means if you add a dependency
34 | that has `.dev` or similar in the version number you will not find a match. To
35 | consider them, add them with `--pre`:
36 |
37 | ```
38 | rye add "Flask==2.0.0rc2" --pre
39 | ```
40 |
41 | ## Development Dependencies
42 |
43 | For dependencies that should only be installed during development pass `--dev`
44 |
45 | ```
46 | rye add --dev black
47 | ```
48 |
49 | These dependencies are stored in the non-standard
50 | [`tool.rye.dev-dependencies`](pyproject.md#toolryedev-dependencies) key.
51 |
52 | To run tools added this way without enabling the virtualenv use [`rye run`](commands/run.md):
53 |
54 | ```
55 | rye run black
56 | ```
57 |
58 | ## Git / Local Dependencies
59 |
60 | To add a local or git dependency, you can pass additional parameters like `--path`
61 | or `--git`:
62 |
63 | ```
64 | rye add Flask --git=https://github.com/pallets/flask
65 | rye add My-Utility --path ./my-utility
66 | ```
67 |
68 | Note that when adding such dependencies, it's necessary to also provide the name
69 | of the package. Additionally for git dependencies all kinds of extra parameters
70 | such as `--tag`, `--rev` or `--branch` are supported.
71 |
72 | When working with local dependencies it's strongly encouraged to configure a
73 | [workspace](pyproject.md#toolryeworkspace).
74 |
--------------------------------------------------------------------------------
/docs/guide/docker.md:
--------------------------------------------------------------------------------
1 | # Building a Container with Docker
2 |
3 | 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.
4 | If that's the case, read on. Else, skip to [the next section](#container-from-a-python-package).
5 |
6 | This guide requires some familiarity with Docker and Dockerfiles.
7 |
8 | ## Container from Source
9 |
10 | 1. Make sure that your project is set up as a [virtual project](./virtual.md).
11 | This means that you can't install it, and it won't mark itself as a dependency.
12 | If you need your project to be installable, go to [the next section](#container-from-a-python-package).
13 |
14 | - Your `pyproject.toml` should contain `virtual = true` under the `[tool.rye]` section. If it's not there, add it and run `rye sync`.
15 | - If you're just setting up a project, run `rye init --virtual` instead of `rye init`.
16 |
17 | 2. Create a `Dockerfile` in your project root with the following content, using [`uv`](https://github.com/astral-sh/uv):
18 |
19 | ```Dockerfile
20 | FROM python:slim
21 |
22 | RUN pip install uv
23 |
24 | WORKDIR /app
25 | COPY requirements.lock ./
26 | RUN uv pip install --no-cache --system -r requirements.lock
27 |
28 | COPY src .
29 | CMD python main.py
30 | ```
31 |
32 | Or, using `pip`:
33 |
34 | ```Dockerfile
35 | FROM python:slim
36 |
37 | WORKDIR /app
38 | COPY requirements.lock ./
39 | RUN PYTHONDONTWRITEBYTECODE=1 pip install --no-cache-dir -r requirements.lock
40 |
41 | COPY src .
42 | CMD python main.py
43 | ```
44 |
45 | 3. You can now build your image like this:
46 |
47 | ```bash
48 | docker build .
49 | ```
50 |
51 | ### Dockerfile Adjustments
52 |
53 | The `Dockerfile`s in this guide are examples. Some adjustments you might want to make:
54 |
55 | - The command (`CMD python src/main.py`) should point to your script.
56 | - Adjust the base image (`FROM python:slim`):
57 | - Prefer a tagged version that matches the one from your `.python-version` file, e.g. `FROM python:3.12.0-slim`.
58 | - The `-slim` variants are generally a good tradeoff between image size and compatibility and should work fine for most workloads.
59 | But you can also use `-alpine` for smaller images (but potential compatibility issues) or no suffix for ones that contain more system tools.
60 | - If you need additional system packages, install them before copying your source code, i.e. before the line `COPY src .`.
61 | When using Debian-based images (i.e. `-slim` or no-suffix variants), that could look like this:
62 |
63 | ```Dockerfile
64 | RUN apt-get update \
65 | && apt-get install -y --no-install-recommends some-dependency another-dependency \
66 | && rm -rf /var/lib/apt/lists/*
67 | ```
68 |
69 | ## Container from a Python Package
70 |
71 | If your code is an installable package, it's recommended that you first build it, then install it inside your Docker image.
72 | This way you can be sure that the image is exactly the same as what a user installation would be.
73 |
74 | An example `Dockerfile` might look like this with [`uv`](https://github.com/astral-sh/uv):
75 |
76 | ```Dockerfile
77 | FROM python:slim
78 | RUN pip install uv
79 | RUN --mount=source=dist,target=/dist uv pip install --no-cache /dist/*.whl
80 | CMD python -m my_package
81 | ```
82 |
83 | To build your docker image, you'll have to first build your wheel, like this:
84 |
85 | ```bash
86 | rye build --wheel --clean
87 | docker build . --tag your-image-name
88 | ```
89 |
90 | Note that this approach bundles your dependencies and code in a single layer.
91 | 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.
92 |
93 | The [Dockerfile adjustments from the previous section](#dockerfile-adjustments) apply.
94 |
95 | ## Explanations
96 |
97 | Rye's lockfile standard is the `requirements.txt` format from `pip` (and used by [`uv`](https://github.com/astral-sh/uv)), so you don't actually need `rye` in your container to be able to install dependencies.
98 | This makes the Dockerfile much simpler and avoids the necessity for multi-stage builds if small images are desired.
99 |
100 | The `--no-cache-dir` and `--no-cache` parameters, passed to `pip` and `uv` respectively, make the image smaller by not
101 | writing any temporary files. While caching can speed up subsequent builds, it's not necessary in a container where the
102 | image is built once and then used many times.
103 |
104 | Similarly, the `PYTHONDONTWRITEBYTECODE=1` environment variable is set to avoid writing `.pyc` files, which are not
105 | needed in a container. (`uv` skips writing `.pyc` files by default.)
106 |
--------------------------------------------------------------------------------
/docs/guide/index.md:
--------------------------------------------------------------------------------
1 | # Introduction
2 |
3 | Rye is still a very experimental tool, but this guide is here to help you get
4 | started. Before we dive into the installation and basic usage guide it's
5 | important for you to understand what Rye actually is.
6 |
7 | Rye is a one-stop-shop tool. The idea is that as a Python developer all you
8 | need to know is Rye, because Rye is your start into the experience. As a Rye
9 | user you do not even need to install Python yourself as Rye does this for you.
10 | This means to use Rye, you just need to install Rye, the rest is done by Rye
11 | itself.
12 |
13 | Once Rye is on your system, it can automatically install Python interpreters
14 | for you, install packages from package indexes, manage virtualenvs behind
15 | the scenes and more.
16 |
17 |
18 |
19 |
20 |
21 | Interested? Then head over to [Installation](./installation.md) to learn about
22 | how to get Rye onto your system. Once that is done, read the [Basics](./basics.md)
23 | to learn about how Rye can be used.
24 |
--------------------------------------------------------------------------------
/docs/guide/publish.md:
--------------------------------------------------------------------------------
1 | # Building and Publishing
2 |
3 | Rye currently uses [build](https://github.com/pypa/build) to build the package and uses [twine](https://github.com/pypa/twine) to publish it.
4 |
5 | ## Build
6 |
7 | By default, `rye` will build both the sdist and wheel targets in the `dist` directory. The command for this is called [`build`](commands/build.md).
8 |
9 | ```
10 | rye build
11 | ```
12 |
13 | You can use the `--sdist` or `--wheel` flag to build the specific target, or specify the output directory with `--out`.
14 |
15 | ```
16 | rye build --wheel --out target
17 | ```
18 |
19 | If you want to clean the build directory before building, run:
20 |
21 | ```
22 | rye build --clean
23 | ```
24 |
25 | ## Publish
26 |
27 | Rye will publish the distribution files under the `dist` directory to PyPI by default.
28 |
29 | ```bash
30 | rye publish
31 | ```
32 |
33 | You might be asked to input your access token and some other info if needed.
34 |
35 | ```
36 | No access token found, generate one at: https://pypi.org/manage/account/token/
37 | Access token:
38 |
39 | ```
40 |
41 | You can also specify the distribution files to be published:
42 |
43 | ```
44 | rye publish dist/example-0.1.0.tar.gz
45 | ```
46 |
47 | ### --repository
48 |
49 | 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:
50 |
51 | ```
52 | rye publish --repository testpypi --repository-url https://test.pypi.org/legacy/
53 | ```
54 |
55 | ### --yes
56 |
57 | You can optionally set the `--yes` flag to skip the confirmation prompt. This can be useful for CI/CD pipelines.
58 |
59 | ```
60 | rye publish --token --yes
61 | ```
62 |
63 | Rye will store your repository info in `$HOME/.rye/credentials` for future use.
64 |
65 | ### --skip-existing
66 |
67 | 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.
68 |
--------------------------------------------------------------------------------
/docs/guide/rust.md:
--------------------------------------------------------------------------------
1 | # Rust Modules
2 |
3 | Rye recommends using [maturin](https://github.com/PyO3/maturin) to develop Rust Python
4 | extension modules. This process is largely automated and new projects can be created
5 | with `rye init`.
6 |
7 | ## New Project
8 |
9 | ```
10 | rye init my-project --build-system maturin
11 | cd my-project
12 | ```
13 |
14 | The following structure will be created:
15 |
16 | ```
17 | .
18 | ├── .git
19 | ├── .gitignore
20 | ├── .python-version
21 | ├── README.md
22 | ├── pyproject.toml
23 | ├── Cargo.toml
24 | ├── python
25 | └── my_project
26 | └── __init__.py
27 | └── src
28 | └── lib.rs
29 | ```
30 |
31 | ## Iterating
32 |
33 | When you use maturin as a build system then `rye sync` will automatically build the rust
34 | extension module into your venv. Likewise `rye build` will use maturin to trigger a
35 | wheel build. For faster iteration it's recommended to use `maturin` directly.
36 |
37 | If you want to use other maturin commands such as `maturin develop` you can install
38 | it as a global tool:
39 |
40 | ```
41 | rye install maturin
42 | ```
43 |
44 | Rye recommends mixed python/rust modules. In that case you can save some valuable
45 | iteration time by running `maturin develop --skip-install`:
46 |
47 | ```
48 | maturin develop --skip-install
49 | ```
50 |
--------------------------------------------------------------------------------
/docs/guide/shims.md:
--------------------------------------------------------------------------------
1 | # Shims
2 |
3 | After installation Rye places two shims on your `PATH`: `python` and `python3`. These
4 | shims have specific behavior that changes depending on if they are used within a Rye
5 | managed project or outside.
6 |
7 | Inside a Rye managed project they resolve to the Python interpreter of the virtualenv.
8 | This means that even if you do not enable the virtualenv, you can just run `python`
9 | in a shell, and it will automatically operate in the right environment.
10 |
11 | Outside a Rye managed project it typically resolves to your system Python, though you
12 | can also opt to have it resolve to a Rye managed Python installation for you. This is
13 | done so that it's not disruptive to your existing workflows which might depend on the
14 | System python installation.
15 |
16 | ## Global Shims
17 |
18 | +++ 0.9.0
19 |
20 | To enable global shims, you need to enable the `global-python` flag in
21 | the [`config.toml`](config.md) file:
22 |
23 | ```bash
24 | rye config --set-bool behavior.global-python=true
25 | ```
26 |
27 | Afterwards if you run `python` outside of a Rye managed project it will
28 | spawn a Python interpreter that is shipped with Rye. It will honor the
29 | closest `.python-version` file for you. Additionally you can also
30 | explicitly request a specific Python version by adding `+VERSION` after
31 | the `python` command. For instance this runs a script with Python 3.8:
32 |
33 | ```bash
34 | python +3.8 my-script.py
35 | ```
36 |
37 | !!! Note
38 |
39 | Selecting a specific Python version this way only works outside of
40 | Rye managed projects. Within Rye managed projects, the version needs
41 | to be explicitly selected via `.python-version` or with the
42 | `requires-python` key in `pyproject.toml`.
43 |
--------------------------------------------------------------------------------
/docs/guide/sources.md:
--------------------------------------------------------------------------------
1 | # Dependency Sources
2 |
3 | +++ 0.2.0
4 |
5 | Normally Rye loads packages from PyPI only. However it is possible to instruct it to
6 | load packages from other indexes as well.
7 |
8 | ## Adding a Source
9 |
10 | An index can be added to a project or workspace (via `pyproject.toml`) or into the
11 | [global config](config.md#config-file). Rye will always consult both files where the
12 | `pyproject.toml` file wins over the global config.
13 |
14 | Each source needs to have a unique name. The default source is always called `default`
15 | and out of the box points to PyPI.
16 |
17 | === "Global Source"
18 |
19 | Add this to `~/.rye/config.toml`:
20 |
21 | ```toml
22 | [[sources]]
23 | name = "company-internal"
24 | url = "https://company.internal/simple/"
25 | ```
26 |
27 | === "Project Source"
28 |
29 | Add this to `pyproject.toml`:
30 |
31 | ```toml
32 | [[tool.rye.sources]]
33 | name = "company-internal"
34 | url = "https://company.internal/simple/"
35 | ```
36 |
37 | +/- 0.4.0
38 |
39 | Sources in the global config are also considered for tool installations.
40 |
41 | ### Index Types
42 |
43 | Rye supports different types of sources and also allows overriding the `default`
44 | PyPI index. If you give another source the name `default`, PyPI will no longer be
45 | used for resolution.
46 |
47 | === "Regular Index"
48 |
49 | ```toml
50 | [[sources]]
51 | name = "company-internal"
52 | url = "https://company.internal/simple/"
53 | type = "index" # this is implied
54 | ```
55 |
56 | === "Find Links"
57 |
58 | ```toml
59 | [[sources]]
60 | name = "company-internal"
61 | url = "https://company.internal/"
62 | type = "find-links"
63 | ```
64 |
65 | === "Default Index"
66 |
67 | ```toml
68 | [[sources]]
69 | name = "default"
70 | url = "https://company.internal/simple/"
71 | ```
72 |
73 | !!! Warning
74 |
75 | Please take note that the default index cannot be of type `find-links`.
76 |
77 | ## Source Types
78 |
79 | The two sources types (`index` vs `find-links`) are determined by the underlying pip
80 | infrastructure:
81 |
82 | ### `index`
83 |
84 | This is a [PEP 503](https://www.python.org/dev/peps/pep-0503/) type index as provided
85 | by tools such as PyPI or [devpi](https://github.com/devpi/devpi). It corresponds to
86 | the arguments `--index-url` or `--extra-index-url` in pip.
87 |
88 | Note: see the [`uv` documentation](https://github.com/astral-sh/uv/blob/main/PIP_COMPATIBILITY.md#packages-that-exist-on-multiple-indexes)
89 | for more on the use of multiple indexes.
90 |
91 | ### `find-links`
92 |
93 | This is a source that can be of a variety of types and has to point to a file path
94 | or hosted HTML page linking to packages. It corresponds to the `--find-links`
95 | argument. The format of the HTML page is somewhat underspecified but generally
96 | all HTML links pointing to `.tar.gz` or `.whl` files are considered.
97 |
98 | ## Index Authentication
99 |
100 | HTTP basic auth is supported for index authentication. It can be supplied in two
101 | ways. `username` and `password` can be directly embedded in the config, or they
102 | can be supplied with environment variables.
103 |
104 | === "Configured Credentials"
105 |
106 | ```toml
107 | [[sources]]
108 | name = "company-internal"
109 | url = "https://company.internal/simple/"
110 | username = "username"
111 | password = "super secret"
112 | ```
113 |
114 | === "Environment Variables"
115 |
116 | ```toml
117 | [[sources]]
118 | name = "company-internal"
119 | url = "https://${INDEX_USERNAME}:${INDEX_PASSWORD}@company.internal/simple/"
120 | ```
121 |
122 | ## SSL/TLS Verification
123 |
124 | By default a source needs to be SSL/TLS protected. If not, rye will refuse to honor
125 | the source. You can override this by setting `verify-ssl` to `false`:
126 |
127 | ```toml
128 | [[sources]]
129 | name = "company-internal"
130 | url = "http://company.internal/simple/"
131 | verify-ssl = false
132 | ```
133 |
--------------------------------------------------------------------------------
/docs/guide/sync.md:
--------------------------------------------------------------------------------
1 | # Syncing and Locking
2 |
3 | Rye uses [`uv`](https://github.com/astral-sh/uv) to manage dependencies.
4 |
5 | In order to download dependencies rye creates two "lockfiles" (called
6 | `requirements.lock` and `requirements-dev.lock`). These are not real lockfiles,
7 | but they fulfill a similar purpose until a better solution has been implemented.
8 |
9 | Whenever `rye sync` is called, it will update lockfiles as well as the
10 | virtualenv. If you only want to update the lockfiles, then `rye lock` can be
11 | used.
12 |
13 | ## Lock
14 |
15 | When locking, some options can be provided to change the locking behavior. These flags are
16 | also all available on `rye sync`.
17 |
18 | ### `--update` / `--update-all`
19 |
20 | Updates a specific or all requirements to the latest and greatest version. Without this flag
21 | a dependency will only be updated if necessary.
22 |
23 | ```
24 | rye lock --update-all
25 | ```
26 |
27 | ### `--features` / `--all-features`
28 |
29 | Python packages can have extra dependencies. By default the local package that is installed
30 | will only be installed with the default features. If for instance you have an extra dependency
31 | this will only be installed if the feature is enabled.
32 |
33 | ```
34 | rye add --optional=web flask
35 | rye lock --features=web
36 | ```
37 |
38 | When working with [workspaces](../workspaces/), the package name needs to be prefixed with a slash:
39 |
40 | ```
41 | rye lock --features=package-name/feature-name
42 | ```
43 |
44 | The `--features` parameter can be passed multiple times and features can also be comma
45 | separated. To turn on all features, the `--all-features` parameter can be used.
46 |
47 | ```
48 | rye lock --all-features
49 | ```
50 |
51 | ### `--pre`
52 |
53 | By default updates and version resolution will not consider pre-releases of packages. If you
54 | do want to include those, pass `--pre`
55 |
56 | ```
57 | rye lock Flask --pre
58 | ```
59 |
60 | ### `--with-sources`
61 |
62 | +++ 0.18.0
63 |
64 | By default (unless the `tool.rye.lock-with-sources` config key is set to `true` in the
65 | `pyproject.toml`) lockfiles are not generated with source references. This means that
66 | if custom sources are used the lockfile cannot be installed via `uv` or `pip`, unless
67 | `--find-links` and other parameters are manually passed. This can be particularly useful
68 | when the lockfile is used for Docker image builds.
69 |
70 | When this flag is passed then the lockfile is generated with references to `--index-url`,
71 | `--extra-index-url` or `--find-links`.
72 |
73 | ```
74 | rye lock --with-sources
75 | ```
76 |
77 | ## Sync
78 |
79 | Syncing takes the same parameters as `lock` and then some. Sync will usually first do what
80 | `lock` does and then use the lockfiles to update the virtualenv.
81 |
82 | ### `--no-lock`
83 |
84 | To prevent the lock step from automatically running, pass `--no-lock`.
85 |
86 | ```
87 | rye sync --no-lock
88 | ```
89 |
90 | ### `--no-dev`
91 |
92 | Only sync based on the production lockfile (`requirements.lock`) instead of the development
93 | lockfile (`requirements-dev.lock`).
94 |
95 | ```
96 | rye sync --no-dev
97 | ```
98 |
99 | ## Platform Compatibility
100 |
101 | By default, lockfiles depend on the platform they were generated on.
102 |
103 | For example, if your project relies on platform-specific packages and you generate
104 | lockfiles on Windows, these lockfiles will include Windows-specific projects.
105 | Consequently, they won't be compatible with other platforms like Linux or macOS.
106 |
107 | To generate a cross-platform lockfile, you can enable uv's `universal` setting
108 | by adding the following to your `pyproject.toml`:
109 |
110 | ```toml
111 | [tool.rye]
112 | universal = true
113 | ```
114 |
--------------------------------------------------------------------------------
/docs/guide/toolchains/cpython.md:
--------------------------------------------------------------------------------
1 | # Portable CPython
2 |
3 | Rye is capable (and prefers) to download its own Python distribution over what
4 | you might already have on your computer. For CPython, the
5 | [indygreg/python-build-standalone](https://github.com/indygreg/python-build-standalone)
6 | builds from the PyOxidizer project are used.
7 |
8 | The motivation for this is that it makes it easy to switch between Python
9 | versions, to have a common experience across different Rye users and to
10 | avoid odd bugs caused by changes in behavior.
11 |
12 | Unfortunately Python itself does not release binaries (or the right types of
13 | binaries) for all operating systems which is why Rye leverages the portable
14 | Python builds from PyOxidizer.
15 |
16 | Unlike many other Python versions you can install on your computer are
17 | non-portable which means that if you move them to a new location on your
18 | machine, or you copy it onto another computer (even with the same operating
19 | system) they will no longer run. This is undesirable for what Rye wants to do.
20 | For one we want the same experience for any of the Python developers, no matter
21 | which operating system they used. Secondly we want to enable self-contained
22 | Python builds later, which requires that the Python installation is portable.
23 |
24 | To achieve this, the Python builds we use come with some changes that are
25 | different from a regular Python build.
26 |
27 | ## Limitations
28 |
29 | The following changes to a regular Python versions you should be aware of:
30 |
31 | * `libedit` instead of `readline`: unfortunately `readline` is GPLv3 licensed
32 | and this is a hazard for redistributions. As such, the portable Python
33 | builds link against the more freely licensed `libedit` instead.
34 |
35 | * `dbm.gnu` is unavailable. This is a rather uncommonly used module and the
36 | standard library provides alternatives.
37 |
38 | Additionally due to how these builds are created, there are some other quirks
39 | you might run into related to terminal support or TKinter. Some of these
40 | issues are collected in the [FAQ](../faq.md). Additionally, the Python
41 | Standalone Builds have a [Behavior Quirks](https://gregoryszorc.com/docs/python-build-standalone/main/quirks.html)
42 | page.
43 |
44 | ## Sources
45 |
46 | Portable CPython builds are downloaded from GitHub
47 | ([indygreg/python-build-standalone/releases](https://github.com/indygreg/python-build-standalone/releases))
48 | and SHA256 hashes are generally validated. Some older versions might not
49 | have hashes available in which case the validation is skipped.
50 |
51 | ## Usage
52 |
53 | When you pin a Python version to `cpython@major.minor.patch` (or just
54 | `major.minor.patch`) then Rye will automatically download the right version
55 | for you whenever it is needed. If a [custom toolchain](index.md#registering-toolchains) has already been registered with that name and
56 | version, that this is used instead.
57 |
--------------------------------------------------------------------------------
/docs/guide/toolchains/pypy.md:
--------------------------------------------------------------------------------
1 | # PyPy
2 |
3 | [PyPy](https://www.pypy.org/) is supported as alternative Python distribution.
4 | Like the portable CPython builds it's downloaded automatically. The name for
5 | PyPy distributions is `pypy`.
6 |
7 | ## Limitations
8 |
9 | PyPy has some limitations compared to regular Python builds when it comes to
10 | working with Rye. Most specifically PyPy uses some internal pypi dependencies
11 | and you might notice warnings show up when syching. PyPy also lags behind
12 | regular Python installations quite a bit these days so you likely need to
13 | target older Python packages.
14 |
15 | ## Sources
16 |
17 | PyPy builds are downloaded from
18 | [downloads.python.org](https://downloads.python.org/pypy/).
19 |
20 | ## Usage
21 |
22 | When you pin a Python version to `pypy@major.minor.patch` then Rye will
23 | automatically download the right version for you whenever it is needed. If a
24 | [custom toolchain](index.md#registering-toolchains) has already been registered
25 | with that name and version, that this is used instead. Note that the version
26 | refers to the PyPy **CPython** version.
27 |
28 | That means for instance that PyPy 7.3.11 is identified as `pypy@3.9.16` as this
29 | is the Python version it provides. As PyPy also lacks builds for some CPU
30 | architectures, not all platforms might provide the right PyPy versions.
31 |
--------------------------------------------------------------------------------
/docs/guide/tools.md:
--------------------------------------------------------------------------------
1 | # Tools
2 |
3 | Rye supports global tool installations. This for instance allows you to install
4 | tools like `black` or `ruff` globally.
5 |
6 | ## Installing Tools
7 |
8 | Use the [`rye tools install`](commands/tools/install.md) (aliased to [`rye
9 | install`](commands/install.md)) command to install a tool globally with a shim:
10 |
11 | ```bash
12 | rye install ruff
13 | ```
14 |
15 | Afterwards the tool is installed into `~/.rye/tools/ruff` and the necessary shims
16 | are placed in `~/.rye/shims`.
17 |
18 | +/- 0.4.0
19 |
20 | The `install` command now considers custom sources configured
21 | in the `config.toml` file. For more information see [Dependency Sources](sources.md).
22 |
23 | ## Extra Requirements
24 |
25 | Some tools do not declare all of their dependencies since they might be optional.
26 | In some cases these can be declared by passing extra features to the installer:
27 |
28 | ```bash
29 | rye install black --features colorama
30 | ```
31 |
32 | If dependencies are not at all specified, then they can be provided with `--extra-requirement`.
33 | This is particularly sometimes necessary if the tool uses `pkg_resources` (part of
34 | `setuptools`) but forgets to declare that dependency:
35 |
36 | ```bash
37 | rye install gradio --extra-requirement setuptools
38 | ```
39 |
40 | ## Listing Tools
41 |
42 | If you want to see which tools are installed, you can use `rye tools list`:
43 |
44 | ```
45 | rye tools list
46 | ```
47 |
48 | ```
49 | black
50 | black
51 | blackd
52 | ruff
53 | ruff
54 | ```
55 |
56 | To also see which scripts those tools provide, also pass `--include-scripts`
57 |
58 | ```
59 | rye tools list --include-scripts
60 | ```
61 |
62 | ## Uninstalling Tools
63 |
64 | To uninstall a tool again, use `rye tools uninstall` (aliased to `rye uninstall`):
65 |
66 | ```
67 | rye uninstall black
68 | ```
69 |
--------------------------------------------------------------------------------
/docs/guide/virtual.md:
--------------------------------------------------------------------------------
1 | # Virtual Projects
2 |
3 | +++ 0.20.0
4 |
5 | Virtual projects are projects which are themselves not installable Python
6 | packages, but that will sync their dependencies. They are declared like a
7 | normal python package in a `pyproject.toml`, but they do not create a package.
8 | Instead the `tool.rye.virtual` key is set to `true`.
9 |
10 | For instance this is useful if you want to use a program like `mkdocs` without
11 | declaring a package yourself:
12 |
13 | ```
14 | rye init --virtual
15 | rye add mkdocs
16 | rye sync
17 | rye run mkdocs
18 | ```
19 |
20 | This will create a `pyproject.toml` but does not actually declare any python code itself.
21 | Yet when syncing you will end up with mkdocs in your project.
22 |
23 | ## Behavior Changes
24 |
25 | When syncing the project itself is never installed into the virtualenv as it's not
26 | considered to be a valid package. Likewise you cannot publish virtual packages to
27 | PyPI or another index.
28 |
29 | ## Limitations
30 |
31 | Virtual projects can not have optional dependencies. These even if declared are not
32 | installed.
33 |
34 | ## Workspaces
35 |
36 | If a [workspace](../workspaces/) does not have a toplevel package it's
37 | recommended that it's declared as virtual.
38 |
--------------------------------------------------------------------------------
/docs/guide/workspaces.md:
--------------------------------------------------------------------------------
1 | # Workspaces
2 |
3 | Workspaces are a feature that allows you to work with multiple packages that
4 | have dependencies on each other. A workspace is declared by setting the
5 | `tool.rye.workspace` key in `pyproject.toml`. Afterwards, all projects within
6 | that workspace share a singular virtualenv.
7 |
8 | ## Declaring Workspaces
9 |
10 | A workspace is declared in the "toplevel" `pyproject.toml`. At the very least
11 | the key `tool.rye.workspace` needs to be added. It's also recommended to
12 | set a glob pattern in the `members` key to prevent accidentally including
13 | unintended folders as projects.
14 |
15 | ```toml
16 | [tool.rye.workspace]
17 | members = ["myname-*"]
18 | ```
19 |
20 | This declares a workspace where all folders starting with the name `myname-`
21 | are considered. If the toplevel workspace itself should not be a project,
22 | then it should be declared as a virtual package:
23 |
24 | ```toml
25 | [tool.rye]
26 | virtual = true
27 |
28 | [tool.rye.workspace]
29 | members = ["myname-*"]
30 | ```
31 |
32 | For more information on that, see [Virtual Packages](../virtual/).
33 |
34 | ## Syncing
35 |
36 | In a workspace, it does not matter which project you are working with, the entire
37 | workspace is synchronized at all times. This has some atypical consequences but
38 | simplifies the general development workflow.
39 |
40 | When a package depends on another package it's first located in the workspace locally
41 | before it's attempted to be downloaded from an index. The `--all-features` flag is
42 | automatically applied to all packages, but to turn on the feature of a specific
43 | package the feature name must be prefixed. For instance to enable the `foo` extra feature
44 | of the `myname-bar` package you would need to do this:
45 |
46 | ```
47 | rye sync --features=myname-bar/foo
48 | ```
49 |
--------------------------------------------------------------------------------
/docs/hooks.py:
--------------------------------------------------------------------------------
1 | import os
2 | import shutil
3 |
4 |
5 | def copy_get(config, **kwargs):
6 | site_dir = config["site_dir"]
7 | shutil.copy("scripts/install.sh", os.path.join(site_dir, "get"))
8 |
--------------------------------------------------------------------------------
/docs/index.md:
--------------------------------------------------------------------------------
1 | ---
2 | hide:
3 | - navigation
4 | ---
5 |
6 |
7 |
8 |
Rye: a Hassle-Free Python Experience
9 |
10 |
11 | !!! note
12 |
13 | If you're getting started with Rye, consider [uv](https://github.com/astral-sh/uv), the
14 | [successor project](https://lucumr.pocoo.org/2024/2/15/rye-grows-with-uv/) from the same maintainers.
15 |
16 | While Rye is actively maintained, uv offers a more stable and feature-complete experience, and is the recommended
17 | choice for new projects.
18 |
19 | Having trouble migrating? [Let us know what's missing.](https://github.com/astral-sh/rye/discussions/1342)
20 |
21 | Rye is a comprehensive project and package management solution for Python.
22 | Born from [its creator's](https://github.com/mitsuhiko) desire to establish a
23 | one-stop-shop for all Python users, Rye provides a unified experience to install and manages Python
24 | installations, `pyproject.toml` based projects, dependencies and virtualenvs
25 | seamlessly. It's designed to accommodate complex projects, monorepos and to
26 | facilitate global tool installations. Curious? [Watch an introduction](https://youtu.be/q99TYA7LnuA).
27 |
28 | A hassle-free experience for Python developers at every level.
29 |
30 |
31 |
3 | 
36 |
37 | 
40 | ```
41 |
42 | [](https://rye.astral.sh)
43 |
--------------------------------------------------------------------------------
/docs/guide/commands/add.md:
--------------------------------------------------------------------------------
1 | # `add`
2 |
3 | Adds a Python package to this project. The command takes a PEP 508 requirement string
4 | but provides additional helper arguments to make this process more user friendly. For
5 | instance instead of passing git references within the requirement string, the `--git`
6 | parameter can be used.
7 |
8 | If auto sync is disabled, after a dependency is added it's not automatically
9 | installed. To do that, you need to invoke the [`sync`](sync.md) command or pass
10 | `--sync`. To remove a dependency again use the [`remove`](remove.md) command.
11 |
12 | +++ 0.26.0
13 |
14 | Added support for auto-sync and the `--sync` / `--no-sync` flags.
15 |
16 | ## Example
17 |
18 | Add the latest version of a dependency that is compatible with the configured Python version:
19 |
20 | ```
21 | $ rye add flask
22 | Added flask>=3.0.1 as regular dependency
23 | ```
24 |
25 | Add a dependency but add an optional extra feature:
26 |
27 | ```
28 | $ rye add flask --features dotenv
29 | Added flask[dotenv]>=3.0.1 as regular dependency
30 | ```
31 |
32 | Add a git dependency:
33 |
34 | ```
35 | $ rye add flask --git https://github.com/pallets/flask
36 | Added flask @ git+https://github.com/pallets/flask as regular dependency
37 | ```
38 |
39 | Add a local dependency:
40 |
41 | ```
42 | $ rye add packagename --path path/to/packagename
43 | Added packagename @ file:///path/to/packagename as regular dependency
44 | ```
45 |
46 | ## Arguments
47 |
48 | * `
8 |