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

ya pkg <SUBCOMMAND>

Subcommands

add

Add one or more packages to package.toml.

Synopsis

ya pkg add <PACKAGES>...

Arguments

PACKAGES · 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.

# 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

Examples

# 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

ya pkg delete <PACKAGES>...

Arguments

PACKAGES · string[] · required

Packages to delete. Use the same format as when adding.

ya pkg delete yazi-rs/plugins:git

Examples

# 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

ya pkg install

Examples

# 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

ya pkg list

Examples

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

ya pkg upgrade [PACKAGES]...

Arguments

PACKAGES · string[]

Packages to upgrade. If not specified, upgrades all packages.

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

# Upgrade all packages
ya pkg upgrade

Examples

# 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:

[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:

# 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:

# 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:

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:

# Clone your config
git clone <your-config-repo> ~/.config/yazi

# Install all packages
ya pkg install

Regular Updates

Keep packages up to date:

# Weekly or monthly
ya pkg upgrade

Testing New Packages

Test packages before committing:

# 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:

   mkdir -p ~/.config/yazi/plugins/my-plugin.yazi
   

2. Develop your plugin:

   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:

   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:

   ya pkg add user/my-plugin
   

Environment Variables

YA_FORCE_ANSI · string

Set to 1 to force ANSI color output in package operations.

YA_FORCE_ANSI=1 ya pkg list

Exit Codes

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

See Also

• ya - Main CLI utility
• yazi - Main Yazi command
• Plugin Development Guide - Creating custom plugins
• Flavor Development Guide - Creating custom themes