Installation
- By downloading and using RuyiSDK, you agree to the license terms and privacy policy.
- This documentation uses
~to represent the current user's home directory. When necessary, please use the absolute path (on most Linux systems, this is typically something like/home/your-username). You may see/home/fooused as a placeholder in examples—please replace it with your actual environment path. - Each installation method supports different operating systems and hardware architectures. Before proceeding, make sure your environment matches the
Supported Architectureslisted in the relevant section.
Let’s begin with installing the RuyiSDK package manager.
There are currently three installation methods available, each suited to different scenarios. Please choose the one that best fits your system and architecture:
-
Install with Precompiled Binary (Recommended)
- Highlights: Broadest OS and hardware support; minimal system requirements.
- Best for: Almost all users, especially beginners looking for a quick setup.
-
Install via System Package Manager
- Highlights: Installed like any regular software using system commands (e.g.,
apt,yum). - Prerequisite: Your Linux distribution must officially include the
ruyipackage.
- Highlights: Installed like any regular software using system commands (e.g.,
-
Install via Python’s pip Tool
- Highlights: Uses Python’s package manager
pipfor installation. - Best for: Users who already have a Python development environment configured.
- Highlights: Uses Python’s package manager
Now, choose the method that suits your system and preferences to get started!
- Install with Precompiled Binary
- Install via System Package Manager
- Install via Python Package Manager
Installing with Precompiled Binaries
Supported Architectures: Linux x86_64 arm64 riscv64
Download the RuyiSDK Package Manager
The RuyiSDK package manager is currently available as precompiled binaries for Linux systems, supporting three architectures: amd64 (i.e., x86_64), arm64, and riscv64. It does not rely on the system’s Python environment, making it broadly compatible across setups.
They are simultaneously published on both GitHub Releases and the ISCAS mirror site:
This guide uses the ISCAS mirror as an example. First, run uname -m to check your system architecture, then download the corresponding binary.
$ wget $ chmod +x ./ruyi$ sudo cp -v ruyi /usr/local/bin/ruyiInstall the RuyiSDK Package Manager
The command above has been auto-generated based on your system architecture. Make sure the binary is named ruyi and placed in a directory included in your PATH.
To verify the installation, run:
$ ruyi version
If the command executes and prints the copyright information, the installation was successful. If unexpected output appears, please check your installation steps and system environment.
- The installed file must be named
ruyi(do not include architecture suffixes). - Ensure the
ruyibinary has executable permissions. - se
echo $PATHto confirm that the directory containingruyiis included in yourPATHenvironment variable.
- If you prefer a custom installation directory, modify the
/usr/local/binpath in the command accordingly, and ensure yourPATHincludes that directory. - Installing
ruyito~/.local/bin/ruyiis often recommended, as it allows installation and removal without superuser privileges. In this case, make sure~/.local/bin/is part of yourPATH.
Installing via System Package Manager
Arch Linux
Supported Architectures: ArchLinux x86_64 arm64 riscv64
Arch Linux users can install and uninstall the Ruyi package manager using the system package manager. Compared to installing precompiled binaries, this method offers easier maintenance and better performance by leveraging the system’s Python environment.
To install from AUR using yay (recommended to run as a regular user):
$ yay -S ruyi
To install from the Arch Linux CN repository, add the following configuration using the ISCAS mirror as an example:
[archlinuxcn]
Server = https://mirror.iscas.ac.cn/archlinuxcn/$arch
Then install using pacman:
$ sudo pacman -Sy
$ sudo pacman -S ruyi
Gentoo Linux
Supported Architectures: GentooLinux x86_64 arm64 riscv64
Gentoo Linux users can follow the steps below to install and configure the Ruyi package manager (ruyi) using the official ruyisdk-overlay.
- Install
eselect-repositoryand the Git client:
$ sudo emerge --ask app-eselect/eselect-repository dev-vcs/git
-
Ensure the main Gentoo repository is added (usually preconfigured by default).
-
Add the
ruyisdk-overlayusingeselect-repository:
$ sudo eselect repository add ruyisdk git https://github.com/ruyisdk/ruyisdk-overlay.git
- Sync the repository:
$ sudo emaint sync -r ruyisdk
- Accept testing keywords (Unmask)
The Ruyi ebuild is marked as testing and needs to be unmasked before installation.
-
First, run the following command to generate the necessary changes to package.accept_keywords:
>_Terminal$ sudo emerge dev-util/ruyi --autounmask-write --autounmask -
Then run
dispatch-confand enteru(use-new) to accept all changes:>_Terminal$ sudo dispatch-conf
- Install the Ruyi package manager:
$ sudo emerge --ask dev-util/ruyi
- Verify your installation:
$ ruyi version
If the command executes successfully and prints version and copyright information, the installation is complete. If it fails, please check your system environment or retry the installation.
Installing via Python Package Manager
Supported Architectures: Linux x86_64 arm64
The RuyiSDK package manager is now available on PyPI (View PyPI Page).
If you're using a Linux system with x86_64 or ARM64 architecture, you can install it via pip or pipx. For Linux systems with RISC-V64 architecture, we recommend using the precompiled binary installation method instead.
Some Python libraries required by ruyi currently lack precompiled RISC-V packages on PyPI. When installing via pip, the package manager will attempt to build these dependencies from source, which is likely to fail and can be very time-consuming. Therefore, this installation method is not recommended for RISC-V devices.
We suggest using the precompiled binary installation method on RISC-V systems.
As Python's support for RISC-V continues to improve, we will periodically review and update compatibility. If you're an adventurous early adopter, feel free to try installing ruyi via pip and share your findings in the RuyiSDK Chinese Community .
Installing Globally with pipx
pipx is a tool for installing Python CLI applications in isolated environments, automatically linking executables to your PATH.
$ pipx install ruyi
Once installed, the ruyi command will be added to your PATH, typically under ~/.local/bin. You can verify the installation with:
$ ruyi version
If the command executes and prints copyright information, the installation was successful. If you encounter errors or the command is not found, please review the installation steps and ensure your environment variables are correctly configured.
Installing in a Virtual Environment
If you prefer to install ruyi within a specific virtual environment (e.g., /path/to/some/venv), use the following approach. Be sure to replace the path with your actual environment location:
# Run pip using the full path
# Note: Replace with your actual environment path
$ /path/to/some/venv/bin/pip install ruyi
The ruyi executable will be located in the virtual environment’s bin directory and will not be added to your system PATH automatically. You can run it using the full path or activate the virtual environment first:
# Run ruyi using full path
# Note: Replace with your actual environment path
$ /path/to/some/venv/bin/ruyi version
# Or activate the virtual environment before running
# Note: Replace with your actual environment path
$ source /path/to/some/venv/bin/activate
$ ruyi version
If the command executes and prints copyright information, the installation was successful.
Getting Started
Ruyi has now been successfully installed on your system. You can explore its usage via the built-in help command or continue reading this documentation.
To display help information:
$ ruyi --help