About LinuxWave

关于LinuxWave

LinuxWave is the official Linux port of MacWave. Starting with MacWave 2.0, the main MacWave project no longer supports Linux, so LinuxWave carries that support forward. It is a package manager that runs on Linux (x86_64 / arm64), designed to host common software packages for Linux software developers.

LinuxWave 是 MacWave 的官方 Linux 移植版。从 MacWave 2.0 起，MacWave 主线不再支持 Linux，LinuxWave 承接了这部分支持。它运行在 Linux（x86_64 / arm64） 上，是一个为 Linux 软件开发者 托管 常用软件包 的 包管理器。

Why LinuxWave

为什么选择 LinuxWave

• One command, install common packages. No more scattered download links.
• Versioned storage. Every binary is stored as package@version, so multiple versions can coexist without conflicting with system tools.
• Optional unversioned links. wave link <package> adds a plain shortcut pointing at the highest installed version, and re-points itself whenever you install or remove versions.
• Fully isolated. Upgrade-proof. LinuxWave operates entirely within its own dedicated directories and never overwrites or links against distribution libraries - the dependency libraries it does ship are relocated into its own tree. Even across major distribution upgrades, your LinuxWave environment remains completely intact and functional.
• No cache, always up to date. Package metadata is fetched live from the infosource branch.
• 10 archive formats, CI-verified. Supports no-extension binaries, .zip, .tar.gz, .tar.bz2, .tar.xz, .tar, .gz,.xz, .bz2, .conda.
• Verify first, extract later. SHA256 is checked before extraction.
• Resumable downloads. Interrupted? Resume with -C. A file that fails mid-transfer is retried up to 5 times automatically, and Ctrl-C stops with a one-line message instead of a Python traceback.
• Lightweight and transparent. Pure Python + Shell. No heavy runtime, no hidden behavior.
• Automatically manage dependencies. Support for software packages with dependencies, using reference counting and automatic dependency management, with no need to handle dependencies manually.

• 一条命令，安装常用软件包。 不再需要到处寻找下载链接。
• 版本化存储。 每个二进制文件都以 package@version 形式存储，因此多个版本可以共存，且不会与系统工具冲突。
• 可选的无版本号链接。 wave link <包名> 会建立一个指向最高已安装版本的普通快捷方式，并在安装或卸载版本时自动改指。
• 完全隔离，无惧升级。 LinuxWave 完全在自己的专用目录中运行，绝不覆盖或链接发行版自带的库——它附带的依赖库会被重定位到自己的目录树内。即使跨越大版本发行版升级，你的 LinuxWave 环境依然完整可用。
• 无缓存，始终最新。 软件包元数据实时从 infosource 分支获取。
• 支持 10 种归档格式，经 CI 验证。 支持无扩展名二进制文件、.zip、.tar.gz、.tar.bz2、.tar.xz、.tar、.gz、.xz、.bz2、.conda。
• 先校验，后解压。 解压前先校验 SHA256。
• 支持断点续传。 下载中断了？用 -C 继续。单个文件传输失败会自动重试，最多 5 次；按 Ctrl-C 只会打印一行提示，不再喷出 Python traceback。
• 轻量透明。 纯 Python + Shell，无重型运行时，无隐藏行为。
• 自动管理依赖。 支持带依赖的软件包，采用引用计数与自动依赖管理，无需手动处理依赖。

Supported Platform

支持的平台

Linux (x86_64 / arm64)

Linux（x86_64 / arm64）

Install LinuxWave

安装 LinuxWave

In the terminal, run:

在终端中运行：

$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/LinuxWaveOrg/LinuxWave/HEAD/lib/install.sh)" && source ~/.bashrc

(If you are using zsh instead of bash, run source ~/.zshrc)

（如果你使用的是 zsh 而非 bash，请运行 source ~/.zshrc）

Requirements: Linux (x86_64 / arm64), Python (3.14 and above), patchelf (for dependency library relocation).

环境要求：Linux（x86_64 / arm64）、Python（3.14 及以上）、patchelf（用于依赖库重定位）。

Unattended install

无人值守安装

For scripts and batch use, the installer takes flags so it never waits for input:

面向脚本与批量场景，安装器提供若干参数，全程不会停下来等待输入：

# script already on disk
$ bash install.sh --silent --dir-option=4

# straight from the repository
$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/LinuxWaveOrg/LinuxWave/HEAD/lib/install.sh)" \
  -- --silent --dir-option=4

--silent (-S) answers the directory menu and the agreement automatically. It needs passwordless sudo, or root, when the chosen directory requires privilege. Without --dir-option, it takes menu entry 1 (~/.local/linuxwave) and prints which default it used, instead of reading a terminal that may not exist. --dir-option=N picks menu entry N (1-5); for the custom entry, append the path after =, as in --dir-option=5=/opt/mylw. Run install.sh --help for the list.

--silent（-S）会自动应答目录菜单与许可协议；当选中的目录需要提权时，它要求免密 sudo 或以 root 运行。不带 --dir-option 时，它会选用默认项 1（~/.local/linuxwave）并说明用的是哪个默认值，而不是去读一个可能并不存在的终端。--dir-option=N 免菜单直接选定第 N 项（1-5）；自定义项要在 = 之后附上路径，例如 --dir-option=5=/opt/mylw。完整参数列表可运行 install.sh --help 查看。

Fetch with /bin/bash -c, and put options after --. Calling /bin/bash by absolute path means a tampered PATH cannot decide which shell runs the script, and curl runs to completion before bash executes anything, so a download that fails partway is not executed as it arrives. -- ends bash’s own options, so everything after it reaches the installer. Writing … --silent instead makes --silent the script name ($0), so it is silently dropped and the installer stops at a prompt nobody is watching; the installer warns when it sees an option in $0.

用 /bin/bash -c 取脚本，并把参数放在 -- 之后。以绝对路径调用 /bin/bash，意味着被篡改的 PATH 无法决定由哪个 shell 来执行脚本；而 curl 会先跑完，bash 才开始执行，因此下载中途失败的内容不会被一边到达一边执行。-- 会结束 bash 自身的选项，其后的一切都原样传给安装器。若写成 … --silent，--silent 就成了脚本名（$0）而被静默丢弃，安装器会停在一个没人看的提示符上；当安装器发现 $0 里是选项时会给出警告。

uninstall.sh is scriptable in the same way: --force skips both confirmations and keeps the linuxwave account, while --remove-user also deletes that account. Add both for a fully unattended removal.

uninstall.sh 同样支持脚本化调用：--force 跳过两次确认并保留 linuxwave 账号；--remove-user 则会连同该账号一并删除。两者同时使用即可完全无人值守地卸载。

Without --force, the uninstaller needs a terminal. It reads the confirmation from /dev/tty and stops when there is none, instead of treating a closed stdin as “yes” - deleting is not reversible. Scripts and CI must say --force explicitly.

不加 --force 时，卸载器需要一个终端。它从 /dev/tty 读取确认，读不到就中止，而不会把已关闭的 stdin 当作「同意」——删除不可逆。脚本与 CI 必须显式写上 --force。

Uninstall LinuxWave

卸载 LinuxWave

To completely remove LinuxWave from your system, run the following command in your terminal:

要从系统中彻底移除 LinuxWave，请在终端中运行以下命令：

$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/LinuxWaveOrg/LinuxWave/HEAD/lib/uninstall.sh)"

Download Directory

下载目录

Installed binaries are stored in (options):

已安装的二进制文件存储于（可选）：

1. ~/.local/linuxwave
2. /opt/linuxwave
3. /usr/local/linuxwave
4. /home/linuxwave/.linuxwave (shared, all users)
5. Custom

Config file is stored in (a system-level install always takes priority):

配置文件存储于（系统级安装始终优先）：

1. /etc/linuxwave_config          system-level install (needs sudo)
2. ~/.config/linuxwave_config     user-level install (no sudo)

A shared install (option 4) always uses /etc/linuxwave_config, so that every user on the machine resolves the same install. It needs patchelf, Python 3.14+ and sudo once; the linuxwave account is created automatically if it does not exist.

共享安装（选项 4）始终使用 /etc/linuxwave_config，以保证全机所有用户解析到同一个安装。需要 patchelf、Python 3.14+，以及一次性提供 sudo；若 linuxwave 账号不存在会自动创建。

Installing packages into a shared tree needs sudo with the full path. Only the linuxwave account and root may write there. sudo searches its own PATH, which does not contain ~/.linuxwave/lib, so sudo wave install … fails with command not found; name the entry point instead: sudo /home/linuxwave/.linuxwave/lib/wave install <package>. A user who cannot write to the tree gets that exact command in the error message. To let several users install without sudo, set up the shared-write group described in .templates/SPECIAL/INSTALL_BY_INTERNET.md.

往共享安装树里装软件包，必须用 sudo 加全路径。只有 linuxwave 账号和 root 能写入该目录。sudo 用的是它自己那套 PATH，里面没有 ~/.linuxwave/lib，所以 sudo wave install … 会报「找不到命令」；请直接写出入口：sudo /home/linuxwave/.linuxwave/lib/wave install <package>。写不进安装树的用户，会在报错信息里原样拿到这条命令。想让多个用户免 sudo 装包，请按 .templates/SPECIAL/INSTALL_BY_INTERNET.md 里说明配置共享写组。

Run Packages

运行软件包

To run a package, run the following commands in your terminal:

要运行某个软件包，请在终端中运行以下命令：

{package_name}@{version}

Use the versioned name {package_name}@{version}, or run wave link {package_name} once and then just type {package_name}.

使用带版本号的名称 {package_name}@{version}，或先运行一次 wave link {package_name}，之后直接输入 {package_name} 即可。

Symlink Management

软链接管理

Once a versionless link exists, LinuxWave keeps it pointing at the right version on its own:

建立不含版本号的软链接后，LinuxWave 会自动维护它指向的版本：

1. If the highest version is uninstalled, the versionless link moves to the highest version that remains, and the uninstalled version's own link goes with it.
2. An install re-points the versionless link at the version it just installed; add --unlink to that install to skip this.
3. If a package has no versions left at all, the versionless link is removed.
4. A versioned name is always callable, whether or not a versionless link exists.

1. 最高版本被卸载后，不含版本号的软链接会改指向剩余版本中的最高版本，被卸载版本自己的软链接一并撤销。
2. 安装会把不含版本号的软链接指向本次安装的版本；本次安装加上 --unlink 可跳过这一步。
3. 某软件包不再有任何版本时，不含版本号的软链接会被撤销。
4. 无论何种情况，含版本号的名称始终可以调用，即使存在不含版本号的软链接。

A manual wave unlink {package_name} is remembered: a later uninstall will not re-create the link for that package.

手动 wave unlink {package_name} 过的软件包会被记住，之后的卸载不会重新为它建立链接。

Command Reference

命令参考

Usage:
  wave <command> [package] [flags]

Commands:
  install     Install a package (Latest Version)
  uninstall   Uninstall a package
  list        List installed packages
  search      Search for a package in the index
  info        Display detailed information about a package
  selfupdate  Update LinuxWave itself
  link        Link installed packages without a version number
  unlink      Remove those unversioned links
  linkquery   Show which version an unversioned link points to
            
Flags:
  -h, --help              Show help for any command
  -V, --version           Print version information
  -v, --verbose           Enable verbose output (show detailed logs)

Global Flags (can be used with any command):
  -C, --continue          Resume interrupted downloads (like curl -C -)
      --proxy string      Specify an HTTP/HTTPS proxy (e.g., http://127.0.0.1:8080)
      --skip-ssl          Skip SSL certificate verification (insecure)
      --limit-rate string Limit download speed (e.g., 200K, 1M, 5M)
      --ver string        Install a specific version of the package

Special Flags:
wave install <pkgname>@<version>   Download certain version(s) of a package
    --unlink                       Leave the unversioned link alone (install / uninstall)
    --all, -a                      Apply to every installed package (link / unlink / linkquery)

Unversioned Links:
wave link <name>                   Link a package to its highest installed version
wave linkquery <name>              Show what <name> is linked to (e.g. 🌊 ffmpeg@9.0)
wave unlink <name>                 Remove that link

Uninstalling a version re-points the link to the next highest one, and removes
the link when no version is left. uninstall --unlink keeps the link as-is, and
refuses to run when that would leave the link pointing at the version you are
removing.

Demo Pictures

演示图片

Supported Packages

支持的软件包

(Listed in alphabetical order)

（按字母顺序排列）

bat           by David Peter
btop          by Aristocratos
dust          by bootandy
eza           by Christina Sørensen and the eza community
fd            by David Peter
ffmpeg        by FFmpeg Team
fzf           by Junegunn Choi
htop          by Hisham Muhammad and the htop team
ipsw          by blacktop
jq            by Stephen Dolan, Nicolas Williams, et al.
ldid          by Jay Freeman (saurik) / Procursus Team
lsd           by Abin Simon
ncdu          by Yoran Heling
palera1n      by palera1n Team
pandoc        by John MacFarlane
rg            by Andrew Gallant
tmux          by Nicholas Marriott and contributors
trollrestore  by JJTech (@JJTech0130)
wget          by GNU Project
zoxide        by Ajeet D'Souza
            

License

许可证

This project is licensed under the MIT License.

本项目基于 MIT 许可证 发布。