Skip to main content

ZSH Dependencies Installation

This guide provides platform-specific installation instructions for the dependencies required by ZSH Support:

  • zsh-syntax-highlighting (required) - Provides syntax highlighting for Forge prompts
  • fd (optional) - Fast file finder for @filename<Tab> file tagging
  • fzf (optional) - Fuzzy finder for interactive file and agent selection
Requirements Overview
  • zsh-syntax-highlighting: Required for syntax highlighting feature
  • fd + fzf: Optional but recommended for fuzzy file finding and agent selection
  • Without these tools, you'll need to type full file paths manually and won't get syntax highlighting

Install zsh-syntax-highlighting (Required)​

zsh-syntax-highlighting provides syntax highlighting for Forge prompts and is required for the advertised syntax highlighting feature.

macOS​

brew install zsh-syntax-highlighting

Ubuntu/Debian​

sudo apt install zsh-syntax-highlighting

Arch Linux​

sudo pacman -S zsh-syntax-highlighting

Fedora​

sudo dnf install zsh-syntax-highlighting

Other Linux Distributions​

Check the official installation guide for distribution-specific instructions.

Oh My Zsh Installation​

If you use Oh My Zsh:

# Clone to Oh My Zsh plugins directory
git clone https://github.com/zsh-users/zsh-syntax-highlighting.git ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-syntax-highlighting

# Add to plugins in ~/.zshrc (must be last plugin)
plugins=(... zsh-syntax-highlighting)

Manual Installation​

For manual installation without a package manager:

# Clone the repository
git clone https://github.com/zsh-users/zsh-syntax-highlighting.git

# Add to ~/.zshrc (must be at the end)
echo "source ${(q-)PWD}/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh" >> ${ZDOTDIR:-$HOME}/.zshrc

Verify zsh-syntax-highlighting Installation​

# Check if the environment variable is set
echo $ZSH_HIGHLIGHT_VERSION

If this returns a version number, the plugin is loaded correctly.

Install fd (Fast File Finder)​

fd is a fast and user-friendly alternative to the traditional find command, used by ZSH Support to quickly locate files in your project.

macOS​

brew install fd

Ubuntu/Debian​

sudo apt install fd-find
Ubuntu/Debian Note

On Ubuntu/Debian systems, the binary is installed as fdfind instead of fd due to a naming conflict. The ZSH integration handles this automatically.

Arch Linux​

sudo pacman -S fd

Other Linux Distributions​

Using cargo (if Rust is installed):

cargo install fd-find

Manual installation from GitHub releases:

  1. Visit fd releases page
  2. Download the appropriate binary for your system
  3. Extract and place in your PATH

Verify fd Installation​

fd --version

Install fzf (Fuzzy Finder)​

fzf is a command-line fuzzy finder that provides the interactive file selection interface in ZSH Support.

macOS​

brew install fzf

Ubuntu/Debian​

sudo apt install fzf

Arch Linux​

sudo pacman -S fzf

Other Linux Distributions​

Manual installation using git:

git clone --depth 1 https://github.com/junegunn/fzf.git ~/.fzf
~/.fzf/install

Using package managers:

  • CentOS/RHEL/Fedora: sudo dnf install fzf or sudo yum install fzf
  • openSUSE: sudo zypper install fzf

Verify fzf Installation​

fzf --version

Configuration and Loading Order​

Critical Loading Order

The order in which you load these components in your .zshrc file is crucial:

  1. All other plugins (git, auto-completion, etc.)
  2. Forge integration: source <($FORGE_BIN extension zsh)
  3. zsh-syntax-highlighting: Must be LAST

Example ~/.zshrc structure:

# Other plugins and configuration
plugins=(git zsh-autosuggestions)

# Forge integration
export FORGE_BIN=forge
source <($FORGE_BIN extension zsh)

# zsh-syntax-highlighting (must be last)
source /usr/share/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh # Linux
# source $(brew --prefix)/share/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh  # macOS

Troubleshooting​

Command Not Found After Installation​

If fd or fzf commands are not found after installation:

  1. Check if they're in your PATH:

    which fd fzf

  2. Restart your terminal or reload your shell configuration:

    source ~/.zshrc

  3. For Ubuntu/Debian fd issues: The binary might be installed as fdfind. Create a symlink:

    ln -s $(which fdfind) ~/.local/bin/fd

Permission Issues​

If you encounter permission errors during installation:

  • Avoid using sudo with cargo install - this can create permission issues
  • Use a package manager instead when available
  • For manual installations, ensure the binary is placed in a directory you own (like ~/.local/bin)

Syntax Highlighting Not Working​

If Forge prompts don't show syntax highlighting:

  1. Verify zsh-syntax-highlighting is installed:

    echo $ZSH_HIGHLIGHT_VERSION

  2. Check loading order in .zshrc - ensure zsh-syntax-highlighting is loaded last

  3. Verify the source path is correct for your installation method

ZSH Support Still Not Working​

After installing all dependencies, if ZSH Support features don't work:

  1. Verify all tools are installed:

    # For syntax highlighting
    echo $ZSH_HIGHLIGHT_VERSION

    # For file tagging (optional)
    fd --version && fzf --version

  2. Reload ZSH configuration:

    source ~/.zshrc

  3. Test the integration:

    : test file tagging @package.json<Tab>

  4. Check the ZSH Support troubleshooting section for additional help.

Platform-Specific Notes​

macOS​

  • Homebrew installation is the most reliable method
  • Both tools integrate seamlessly with the system PATH

Linux​

  • Most modern distributions include both tools in their repositories
  • Ubuntu/Debian users should be aware of the fdfind vs fd naming

Windows (WSL)​

  • Use the Linux installation methods within WSL
  • Ensure your WSL distribution is up to date before installing

Alternative Installation Methods​

If the standard installation methods don't work for your system:

Using Nix​

nix-env -i fd fzf

Using Snap (Ubuntu)​

sudo snap install fd fzf

Building from Source​

Both tools are written in Rust and can be built from source:

fd:

git clone https://github.com/sharkdp/fd.git
cd fd
cargo build --release

fzf:

git clone https://github.com/junegunn/fzf.git
cd fzf
make install

zsh-syntax-highlighting:

git clone https://github.com/zsh-users/zsh-syntax-highlighting.git
cd zsh-syntax-highlighting
# Follow manual installation instructions from the repository