> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/sxyazi/yazi/llms.txt
> Use this file to discover all available pages before exploring further.

# pkg

> Package management for Yazi plugins and flavors

## Overview

The `pkg` subcommand manages Yazi packages, including plugins and flavors. Packages are stored in `~/.config/yazi/package.toml` and installed from GitHub repositories.

## Synopsis

```bash theme={null}
ya pkg <SUBCOMMAND>
```

## Subcommands

### add

Add one or more packages to `package.toml`.

#### Synopsis

```bash theme={null}
ya pkg add <PACKAGES>...
```

#### Arguments

<ParamField path="PACKAGES" type="string[]" required>
  Packages to add in the format `owner/repo` or `owner/repo:child`.

  * For simple repositories: `owner/repo.yazi`
  * For monorepos with multiple packages: `owner/repo:package-name`

  Package names must be in kebab-case.

  ```bash theme={null}
  # Add a plugin from a simple repo
  ya pkg add yazi-rs/plugins:git

  # Add a flavor
  ya pkg add catppuccin/yazi

  # Add multiple packages
  ya pkg add yazi-rs/plugins:git yazi-rs/plugins:chmod
  ```
</ParamField>

#### Examples

```bash theme={null}
# Add Git plugin from yazi-rs/plugins monorepo
ya pkg add yazi-rs/plugins:git

# Add a theme/flavor
ya pkg add catppuccin/yazi

# Add multiple plugins at once
ya pkg add yazi-rs/plugins:git yazi-rs/plugins:chmod yazi-rs/plugins:diff
```

#### Package URL Format

Packages are specified using GitHub repository paths:

* **Simple repository**: `owner/repo`
  * Resolves to `owner/repo.yazi`
  * Package name becomes `repo.yazi`
* **Monorepo with child**: `owner/repo:child`
  * Resolves to repository `owner/repo`
  * Installs only the `child.yazi` subdirectory
  * Package name becomes `child.yazi`

#### Installation Location

* **Plugins**: `~/.config/yazi/plugins/<name>.yazi`
* **Flavors**: `~/.config/yazi/flavors/<name>.yazi`

### delete

Delete one or more packages from `package.toml`.

#### Synopsis

```bash theme={null}
ya pkg delete <PACKAGES>...
```

#### Arguments

<ParamField path="PACKAGES" type="string[]" required>
  Packages to delete. Use the same format as when adding.

  ```bash theme={null}
  ya pkg delete yazi-rs/plugins:git
  ```
</ParamField>

#### Examples

```bash theme={null}
# Delete a plugin
ya pkg delete yazi-rs/plugins:git

# Delete multiple packages
ya pkg delete yazi-rs/plugins:git yazi-rs/plugins:chmod

# Delete a flavor
ya pkg delete catppuccin/yazi
```

#### Behavior

* Removes package from `package.toml`
* Deletes package files from `~/.config/yazi/plugins/` or `~/.config/yazi/flavors/`
* Removes package cache from `~/.local/state/yazi/packages/`

### install

Install all packages listed in `package.toml`.

#### Synopsis

```bash theme={null}
ya pkg install
```

#### Examples

```bash theme={null}
# Install all packages
ya pkg install
```

#### Behavior

* Clones or updates Git repositories for all packages
* Extracts and deploys package files to the config directory
* Updates package metadata (revision, hash) in `package.toml`
* Useful after:
  * Fresh Yazi installation
  * Syncing config to a new machine
  * Manually editing `package.toml`

### list

List all installed packages.

#### Synopsis

```bash theme={null}
ya pkg list
```

#### Examples

```bash theme={null}
ya pkg list
```

#### Output Format

```
Plugins:
    yazi-rs/plugins:git (abc123)
    yazi-rs/plugins:chmod (def456)
Flavors:
    catppuccin/yazi (789xyz)
```

Revision hashes are shown in parentheses if available.

### upgrade

Upgrade one, multiple, or all packages.

#### Synopsis

```bash theme={null}
ya pkg upgrade [PACKAGES]...
```

#### Arguments

<ParamField path="PACKAGES" type="string[]" optional>
  Packages to upgrade. If not specified, upgrades all packages.

  ```bash theme={null}
  # Upgrade specific packages
  ya pkg upgrade yazi-rs/plugins:git

  # Upgrade all packages
  ya pkg upgrade
  ```
</ParamField>

#### Examples

```bash theme={null}
# Upgrade all packages
ya pkg upgrade

# Upgrade specific plugin
ya pkg upgrade yazi-rs/plugins:git

# Upgrade multiple packages
ya pkg upgrade yazi-rs/plugins:git yazi-rs/plugins:chmod
```

#### Behavior

* Fetches latest changes from Git repositories
* Updates package files in config directory
* Updates revision hash in `package.toml`
* Preserves local modifications are handled by Git

## Package Structure

### package.toml

Packages are stored in `~/.config/yazi/package.toml`:

```toml theme={null}
[plugin]
deps = [
    { use = "yazi-rs/plugins:git", rev = "abc123def", hash = "xyz789" },
    { use = "yazi-rs/plugins:chmod", rev = "def456ghi", hash = "uvw012" },
]

[flavor]
deps = [
    { use = "catppuccin/yazi", rev = "789abcdef", hash = "stu345" },
]
```

### Dependency Fields

* `use` - Package identifier (`owner/repo` or `owner/repo:child`)
* `rev` - Git revision (commit hash) currently installed
* `hash` - Content hash for verification

### Cache Location

Git repositories are cached in:

```
~/.local/state/yazi/packages/<hash>/
```

The hash is computed from the repository URL to avoid conflicts.

## Plugin Types

### Plugins

Plugins extend Yazi functionality. A plugin package contains:

* `main.lua` - Plugin entry point (required)
* Additional `.lua` files (optional)
* `README.md` - Documentation (optional)
* `LICENSE` - License file (optional)

Installed to: `~/.config/yazi/plugins/<name>.yazi/`

### Flavors

Flavors customize Yazi appearance. A flavor package contains:

* `flavor.toml` - Theme configuration (required)
* `tmtheme.xml` - TextMate theme for syntax highlighting (optional)
* `preview.png` - Preview image (optional)
* `README.md` - Documentation (optional)
* `LICENSE` files - License files (optional)

Installed to: `~/.config/yazi/flavors/<name>.yazi/`

## Monorepo Support

Yazi supports monorepos containing multiple packages. Use the `:child` syntax:

```bash theme={null}
# The yazi-rs/plugins repo contains multiple plugins
ya pkg add yazi-rs/plugins:git      # Installs just the git plugin
ya pkg add yazi-rs/plugins:chmod    # Installs just the chmod plugin
```

Each child is:

* A subdirectory in the repository
* Named with `.yazi` suffix
* Deployed independently to the config directory

## Error Handling

Commands may fail with errors:

```bash theme={null}
# Package already exists
ya pkg add yazi-rs/plugins:git
# Plugin `git` already exists in package.toml

# Package not found
ya pkg delete nonexistent/package
# `nonexistent/package` was not found in package.toml

# Invalid package name
ya pkg add invalid_name/repo
# Package name `invalid_name` must be in kebab-case

# Invalid URL format
ya pkg add invalid-url
# Package URL `invalid-url` must be in the format `owner/repository`
```

## Best Practices

### Version Control

Commit `package.toml` to version control:

```bash theme={null}
cd ~/.config/yazi
git add package.toml
git commit -m "Add git plugin"
```

This allows you to:

* Track package changes
* Share configuration across machines
* Roll back to previous package versions

### Fresh Installation

On a new machine:

```bash theme={null}
# Clone your config
git clone <your-config-repo> ~/.config/yazi

# Install all packages
ya pkg install
```

### Regular Updates

Keep packages up to date:

```bash theme={null}
# Weekly or monthly
ya pkg upgrade
```

### Testing New Packages

Test packages before committing:

```bash theme={null}
# Add and test
ya pkg add yazi-rs/plugins:new-plugin

# If it works well, commit package.toml
# If not, remove it
ya pkg delete yazi-rs/plugins:new-plugin
```

## Package Development

To develop a package:

1. Create package structure:
   ```bash theme={null}
   mkdir -p ~/.config/yazi/plugins/my-plugin.yazi
   ```

2. Develop your plugin:
   ```bash theme={null}
   cd ~/.config/yazi/plugins/my-plugin.yazi
   # Create main.lua and other files
   ```

3. Test locally without adding to `package.toml`

4. Publish to GitHub:
   ```bash theme={null}
   git init
   git add .
   git commit -m "Initial commit"
   git remote add origin https://github.com/user/my-plugin.yazi.git
   git push -u origin main
   ```

5. Others can install with:
   ```bash theme={null}
   ya pkg add user/my-plugin
   ```

## Environment Variables

<ParamField path="YA_FORCE_ANSI" type="string">
  Set to `1` to force ANSI color output in package operations.

  ```bash theme={null}
  YA_FORCE_ANSI=1 ya pkg list
  ```
</ParamField>

## Exit Codes

* `0` - Success
* `1` - Error (package not found, Git error, network error, etc.)

## See Also

* [ya](ya) - Main CLI utility
* [yazi](yazi) - Main Yazi command
* [Plugin Development Guide](#) - Creating custom plugins
* [Flavor Development Guide](#) - Creating custom themes