pkg

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.

​

Overview

​

Synopsis

ya pkg <SUBCOMMAND>

​

Subcommands

​

add

​

Synopsis

ya pkg add <PACKAGES>...

​

Arguments

# 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

• 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

​

Synopsis

ya pkg delete <PACKAGES>...

​

Arguments

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

​

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

​

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)

​

upgrade

​

Synopsis

ya pkg upgrade [PACKAGES]...

​

Arguments

# 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

[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

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

​

Plugin Types

​

Plugins

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

​

Flavors

• 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)

​

Monorepo Support

# 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

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

​

Error Handling

# 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

cd ~/.config/yazi
git add package.toml
git commit -m "Add git plugin"

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

​

Fresh Installation

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

# Install all packages
ya pkg install

​

Regular Updates

# Weekly or monthly
ya pkg upgrade

​

Testing New Packages

# 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

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=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