zoi-rs

Universal Package Manager & Environment Setup Tool

Zoi is a universal package manager and environment setup tool, designed to simplify package management and environment configuration across multiple operating systems.

✨ Features

• Cross-Platform: Works seamlessly on Linux, macOS, and Windows.
• Dynamic Package Definitions: Define packages with dynamic Lua scripts (.pkg.lua) for maximum flexibility.
• Universal Package Support: Install packages from pre-built binaries, compressed archives, or build them from source.
• Extensive Dependency Management: Integrates with over 40 system and language package managers (apt, brew, cargo, npm, pip, go, bun, etc.).
• Rich Dependencies: Define runtime and build dependencies with required, optional, and selectable options.
• Project Environments: Manage project-specific commands and environments using a local zoi.yaml file.
• Repository-Based: Use official, community, or your own private/public Git-based repositories. Manage multiple registries.
• Secure & Verifiable: Verifies package integrity with checksums and authenticity with GPG signatures. Includes a built-in PGP key manager and handles configuration file updates safely.
• Advanced Dependencies: Supports virtual packages (provides) and package replacement (replaces).
• Versatile Package Types: Supports different types of packages:
  • Package: A standard software package.
  • Collection: A meta-package that groups other packages together.
  • App: A template for bootstrapping new projects (zoi create).
  • Extension: A package to extend Zoi's own functionality or configuration.
• Local Package Development: A dedicated zoi package command set (build, install) to streamline creating and testing packages locally.
• Advanced CLI Tools:
  • zoi man: Read package manuals in the terminal.
  • zoi why: Understand why a package is installed.
  • zoi rollback: Revert a package to its previous version or rollback the last transaction.
  • zoi pin: Pin a package to a specific version.
  • zoi exec: Run a package's binary without installing it.
• Library Support: Core functionality is available as a Rust library to be integrated into other applications.

💓 Special Thanks

Thanks you all for helping with developing Zoi.

• GitLab: For offering their Ultimate plan for OSS projects.
• Cloudflare: For offering their Pro plan through Project Alexandria.

🚀 Getting Started

Getting started with Zoi is simple. Just follow these three steps:

1. Install Zoi: Choose one of the installation methods below.

2. Sync Repositories: Before you can install packages, you need to sync the package repositories.

   zoi sync
   

3. Install a Package: Now you can install any package you want. For example, to install hello:

   zoi install @zillowe/hello
   

📦 Installation

You can install Zoi using a package manager, an installer script, or by building it from source.

📜 Scripts

You can also use our installer scripts for a quick setup.

Linux / macOS :

curl -fsSL https://zillowe.pages.dev/scripts/zoi/install.sh | bash

Windows:

powershell -c "irm zillowe.pages.dev/scripts/zoi/install.ps1|iex"

Package Managers

Linux

Install Zoi on Linux distros.

Arch Linux (AUR)

Install zoi-bin (Pre-compiled binary) or zoi (built from source) from the AUR using your favorite helper (e.g. yay, paru):

yay -S zoi-bin

Or manually without any helpers:

git clone https://aur.archlinux.org/zoi-bin.git
cd zoi-bin
makepkg -si

Fedora

Install zoi-rs on Fedora from Terra repo (not maintained by us so updates can be late, uses Crates.io version):

# add terra repo
dnf install --nogpgcheck --repofrompath 'terra,https://repos.fyralabs.com/terra$releasever' terra-release
# install Zoi
sudo dnf install zoi-rs

More information and instructions for using Terra are available here.

macOS

Install Zoi on macOS.

Homebrew

Install Zoi using Homebrew (Also supports linux):

brew install Zillowe/tap/zoi

Windows

Install Zoi on Windows.

Scoop

Install Zoi using Scoop:

scoop bucket add zillowe https://github.com/Zillowe/scoop.git
scoop install zoi

Crates.io

You can install zoi directly from crates.io using cargo:

cargo install zoi-rs

NPM

You can install @zillowe/zoi from npm also.

npx @zillowe/zoi
bunx @zillowe/zoi
pnpm dlx @zillowe/zoi
yarn dlx @zillowe/zoi

🛠️ Build from Source

If you prefer, you can build Zoi from source. You'll need Rust installed.

Build the release binary:

# For Linux/macOS
./scripts/build-release.sh

# For Windows
./scripts/build-release.ps1

Install it locally:

./configure
make build
sudo make install
# (optional) Install CLI completions and setup Zoi's PATH
make setup

🔗 Dependencies Support

What dependency installation we support.

And many more.

For more dependencies and information please visit the Dependencies Page on Docs.

Some of the package manager are OS specific, so when a dependency is in that package manager it only installs it for that OS.

But some other package managers like npm, it installs the dependency if the package manager is available.

💡 Usage

Here are some common commands to get you started.

• Install a package:

  zoi install <package_name>
  

• Uninstall a package:

  zoi uninstall <package_name>
  

• Update packages:

  # Update all installed packages
  zoi update --all
  
  # Update specific packages
  zoi update <package1> <package2>
  

• Search for a package:

  zoi search <term>
  

• Show package details:

  zoi show <package_name>
  

• Run a project command:

  # Run a command defined in zoi.yaml
  zoi run <command_alias>
  

• Add a new repository:

  # Interactively
  zoi repo add
  
  # By name from the default registry
  zoi repo add <repo_name>
  
  # From a git repo URL
  zoi repo add https://github.com/<user_name>/<repo_name>.git
  

• Update Zoi to the latest version:

  zoi upgrade
  

For more detailed information, please refer to the Docs.

📦 Packaging Status

🤝 Contributing

We welcome contributions from the community! If you'd like to contribute, please read our Contributing Guidelines for more information.

New features, enhancements and bug reports are welcome.

📚 Repositories & Mirrors

Zoi is hosted on multiple forges. The primary locations and mirrors are:

• Zoi Source Code (this repo)

  • Primary: GitLab
  • Mirrors: GitHub, Codeberg

• Packages Database (Zoidberg)

  • Primary: GitLab
  • Mirrors: GitHub, Codeberg

Repository tiers

Repository tiers for Zoidberg, Zoi's official packages repo.

• Core: Essential packages, libraries and very common/maintained packages.
• Main: Packages that don't fit in Core but are essential for most people.
• Extra: Packages that are new, not very common or maintained, not preferable.
• Community: User submitted packages that are new, can be upgraded to a higher repo.
• Test: Testing repo for new Zoi features and for new packages before release.
• Archive: Archived packages that are no longer maintained.
• Zillowe: Zillowe's own official packages.

For details and CLI usage examples, see the docs page: Repositories.

📜 License

Zoi is licensed under the Apache 2.0 License.