<div align="center">
<img width="320" hspace="10" alt="Zoi Banner" src="https://gitlab.com/Zillowe/Zillwen/Zusty/Zoi/-/raw/main/app/images/zoi-banner.svg"/>
<p><strong>Universal Package Manager & Environment Setup Tool</strong></p>
</div>
<hr/>
<br/>
<div align="center">
<a href="https://gitlab.com/Zillowe/Zillwen/Zusty/Zoi/-/releases">
<img alt="GitLab Latest Release" src="https://img.shields.io/gitlab/v/release/Zillowe%2FZillwen%2FZusty%2FZoi?sort=date&display_name=release&style=flat&logo=gitlab&logoColor=%23fff&label=Release&labelColor=%235452f1&color=%23282696"/>
</a>
<a href="https://gitlab.com/Zillowe/Zillwen/Zusty/Zoi/-/pipelines">
<img alt="GitLab Pipeline Status" src="https://img.shields.io/gitlab/pipeline-status/Zillowe%2FZillwen%2FZusty%2FZoi?style=flat&logo=gitlab&logoColor=%23fff&label=Pipeline&labelColor=%235452f1"/>
</a>
<br/>
<a href="https://aur.archlinux.org/packages/zoi-bin">
<img alt="AUR Version" src="https://img.shields.io/aur/version/zoi-bin?style=flat&logo=archlinux&logoColor=%23ffff&label=AUR&labelColor=5452f1&color=282696"/>
</a>
<a href="https://github.com/Zillowe/homebrew-tap">
<img alt="Homebrew Version" src="https://img.shields.io/badge/dynamic/regex?url=https%3A%2F%2Fraw.githubusercontent.com%2FZillowe%2Fhomebrew-tap%2Frefs%2Fheads%2Fmain%2Fzoi.rb&search=version%5Cs%2B%22(%5B%5E%22%5D%2B)%22&replace=%241&style=flat&logo=homebrew&logoColor=%23ffff&label=Homebrew&labelColor=%235452f1&color=%23282696">
</a>
<a href="https://github.com/Zillowe/scoop">
<img alt="Scoop Version" src="https://img.shields.io/scoop/v/zoi?bucket=https%3A%2F%2Fgithub.com%2FZillowe%2Fscoop&style=flat&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPCFET0NUWVBFIHN2ZyBQVUJMSUMgIi0vL1czQy8vRFREIFNWRyAxLjEvL0VOIiAiaHR0cDovL3d3dy53My5vcmcvR3JhcGhpY3MvU1ZHLzEuMS9EVEQvc3ZnMTEuZHRkIj4NCjwhLS0gVXBsb2FkZWQgdG86IFNWRyBSZXBvLCB3d3cuc3ZncmVwby5jb20sIFRyYW5zZm9ybWVkIGJ5OiBTVkcgUmVwbyBNaXhlciBUb29scyAtLT4KPHN2ZyB3aWR0aD0iODAwcHgiIGhlaWdodD0iODAwcHgiIHZpZXdCb3g9IjAgMCAyNCAyNCIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIiBmaWxsPSIjZmZmZmZmIj4KDTxnIGlkPSJTVkdSZXBvX2JnQ2FycmllciIgc3Ryb2tlLXdpZHRoPSIwIi8%2BCg08ZyBpZD0iU1ZHUmVwb190cmFjZXJDYXJyaWVyIiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiLz4KDTxnIGlkPSJTVkdSZXBvX2ljb25DYXJyaWVyIj4gPHRpdGxlPm1pY3Jvc29mdDwvdGl0bGU%2BIDxyZWN0IHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgZmlsbD0ibm9uZSIvPiA8cGF0aCBkPSJNMiwzaDl2OUgyVjNtOSwxOUgyVjEzaDl2OU0yMSwzdjlIMTJWM2g5bTAsMTlIMTJWMTNoOVoiLz4gPC9nPgoNPC9zdmc%2B&logoColor=%23ffff&label=Scoop&labelColor=%235452f1&color=%23282696"/>
</a>
<br/>
<a href="https://crates.io/crates/zoi-rs">
<img alt="Crates.io Version" src="https://img.shields.io/crates/v/zoi-rs?style=flat&logo=rust&logoColor=%23ffff&label=Crates.io&labelColor=%235452f1&color=%23282696">
</a>
</div>
<br/>
<div align="center">
<a href="https://zillowe.qzz.io/docs/zds/zoi"><strong>Docs</strong></a> •
<a href="https://discord.gg/P4R7yaA3hf"><strong>Discord</strong></a> •
<a href="./SECURITY.md"><strong>Security</strong></a> •
<a href="./CONTRIBUTING.md"><strong>Contributing</strong></a> •
<a href="./CHANGELOG.md"><strong>Changelog</strong></a>
<br/>
<a href="https://gitlab.com/Zillowe/Zillwen/Zusty/Zoi/-/issues/new?issuable_template=Bug%20Report"><strong>Report a Bug</strong></a> •
<a href="https://gitlab.com/Zillowe/Zillwen/Zusty/Zoi/-/issues/new?issuable_template=Feature%20Request"><strong>Request a Feature</strong></a> •
<a href="https://gitlab.com/Zillowe/Zillwen/Zusty/Zoi/-/issues/new?issuable_template=Enhancement%20Request"><strong>Request an Enhancement</strong></a>
<br/>
<a href="./CODE_OF_CONDUCT.md"><strong>Code of Conduct</strong></a> •
<a href="./PACKAGING.md"><strong>Packaging</strong></a> •
<a href="./RELEASE.md"><strong>Release Guidelines</strong></a>
</div>
<br/>
<hr/>
<br/>
<details>
<summary>Table of Contents</summary>
- [Features](#-features)
- [Special Thanks](#-special-thanks)
- [Getting Started](#-getting-started)
- [Installation](#-installation)
- [Package Managers](#package-managers)
- [Scripts](#-scripts)
- [Linux](#linux)
- [Arch Linux (AUR)](#arch-linux-aur)
- [Fedora](#fedora)
- [macOS](#macos)
- [Homebrew](#homebrew)
- [Windows](#windows)
- [Scoop](#scoop)
- [Crates.io](#cratesio)
- [NPM](#npm)
- [Build from Source](#%EF%B8%8F-build-from-source)
- [Dependencies Support](#-dependencies-support)
- [Usage](#-usage)
- [Packaging Status](#-packaging-status)
- [Repositories & Mirrors](#-repositories--mirrors)
- [Contributing](#-contributing)
- [License](#-license)
</details>
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.
- **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](https://gitlab.com): For offering their Ultimate plan for OSS projects.
- [Cloudflare](https://cloudflare.com): For offering their Pro plan through [Project Alexandria](https://www.cloudflare.com/lp/project-alexandria).
## 🚀 Getting Started
Getting started with Zoi is simple. Just follow these three steps:
1. **Install Zoi:**
Choose one of the [installation methods](#-installation) below.
2. **Sync Repositories:**
Before you can install packages, you need to sync the package repositories.
```sh
zoi sync
```
3. **Install a Package:**
Now you can install any package you want. For example, to install `hello`:
```sh
zoi install 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 :**
```sh
curl -fsSL https://zillowe.pages.dev/scripts/zoi/install.sh | bash
```
**Windows:**
```powershell
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`](https://aur.archlinux.org/packages/zoi-bin) (Pre-compiled binary) or [`zoi`](https://aur.archlinux.org/packages/zoi) (built from source) from the AUR using your favorite helper (e.g. `yay`, `paru`):
```sh
yay -S zoi-bin
```
Or manually without any helpers:
```sh
git clone https://aur.archlinux.org/zoi-bin.git
cd zoi-bin
makepkg -si
```
##### Fedora
Install `zoi-rs` on Fedora from [Terra](https://terra.fyralabs.com) repo (not maintained by us so updates can be late, uses [Crates.io](#cratesio) version):
```sh
# 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](https://developer.fyralabs.com/terra/installing).
#### macOS
Install Zoi on macOS.
##### Homebrew
Install Zoi using Homebrew (Also supports linux):
```sh
brew install Zillowe/tap/zoi
```
#### Windows
Install Zoi on Windows.
##### Scoop
Install Zoi using Scoop:
```powershell
scoop bucket add zillowe https://github.com/Zillowe/scoop.git
scoop install zoi
```
#### Crates.io
You can install `zoi` directly from [crates.io](https://crates.io/crates/zoi-rs) using `cargo`:
```sh
cargo install zoi-rs
```
#### NPM
You can install `@zillowe/zoi` from `npm` also.
```sh
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](https://www.rust-lang.org) installed.
**Build the release binary:**
```sh
# For Linux/macOS
./scripts/build-release.sh
# For Windows
./scripts/build-release.ps1
```
**Install it locally:**
```sh
./configure
make build
sudo make install
# (optional) Install CLI completions and setup Zoi's PATH
make setup
```
## 🔗 Dependencies Support
What dependency installation we support.
| Manager | Ecosystem / OS | Example |
| ---------------- | ------------------------------- | ------------------------------------------------------------------------------- |
| `zoi` | Zoi | `zoi:my-other-package` |
| `native` | System's native package manager | `native:openssl` |
| `script` | Script execution | `script:website.com/install` |
| `apt`, `apt-get` | Debian, Ubuntu, etc. | `apt:libssl-dev` |
| `pacman` | Arch Linux | `pacman:base-devel` |
| `aur` | Arch Linux (AUR) | `aur:visual-studio-code-bin` |
| `brew` | macOS (Homebrew) | `brew:node` |
| `scoop` | Windows | `scoop:git` |
| `snap` | Linux (Snapcraft) | `snap:node` |
| `flatpak` | Linux (Flathub) | `flatpak:org.gimp.GIMP` |
| `npm` | Node.js | `npm:typescript` |
| `bun` | Bun | `bun:elysia` |
| `deno` | Deno | `deno:npm-chalk` or `deno:jsr-@std/bytes` (the `-` instead of `:` is important) |
| `jsr` | JavaScript Registry | `jsr:@std/http` |
| `pip` | Python | `pip:requests` |
| `nix` | NixOS / Nix | `nix:nixpkgs.hello` |
And many more.
For more dependencies and information please visit the [Dependencies Page](https://zillowe.qzz.io/docs/zds/zoi/dependencies) 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:**
```sh
zoi install <package_name>
```
- **Uninstall a package:**
```sh
zoi uninstall <package_name>
```
- **Update packages:**
```sh
# Update all installed packages
zoi update --all
# Update specific packages
zoi update <package1> <package2>
```
- **Search for a package:**
```sh
zoi search <term>
```
- **Show package details:**
```sh
zoi show <package_name>
```
- **Run a project command:**
```sh
# Run a command defined in zoi.yaml
zoi run <command_alias>
```
- **Add a new repository:**
```sh
# 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:**
```sh
zoi upgrade
```
For more detailed information, please refer to the [Docs](https://zillowe.qzz.io/docs/zds/zoi).
## 📦 Packaging Status
[](https://repology.org/project/zoi/versions)
## 🤝 Contributing
We welcome contributions from the community! If you'd like to contribute, please read our [Contributing Guidelines](./CONTRIBUTING.md) 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](https://gitlab.com/Zillowe/Zillwen/Zusty/Zoi)
- Mirrors: [GitHub](https://github.com/Zillowe/Zoi), [Codeberg](https://codeberg.org/Zillowe/Zoi)
- Packages Database (Zoidberg)
- Primary: [GitLab](https://gitlab.com/Zillowe/Zillwen/Zusty/Zoidberg)
- Mirrors: [GitHub](https://github.com/Zillowe/Zoidberg), [Codeberg](https://codeberg.org/Zillowe/Zoidberg)
### Repository tiers
Repository tiers for [Zoidberg](https://gitlab.com/Zillowe/Zillwen/Zusty/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](https://zillowe.qzz.io/docs/zds/zoi/repositories).
## 📜 License
Zoi is licensed under the [Apache 2.0 License](./LICENSE).
<hr/>
<div align="center">
<p>Zoi is developed by Zusty < Zillowe Foundation<br/>Part of the <a href="https://zillowe.qzz.io/docs/zds">Zillowe Development Suite (ZDS)</a></p>
</div>