zoxide not working - Troubleshooting Guide

If zoxide is installed but not working as expected, this guide will help you diagnose and fix the issue.

Common Issues

Issue 1: zoxide Commands Not Recognized

Symptoms:

• z command not found
• zi command not found
• "command not found" errors

Solutions:

1. Verify shell configuration is loaded:

2. Reload shell configuration:

3. Check if zoxide binary exists:

Issue 2: zoxide Not Learning Directories

Symptoms:

• zoxide doesn't remember visited directories
• z command always fails to find directories
• No history is being built

Solutions:

1. Check database location:

2. Verify permissions:

3. Check environment variables:

4. Manually add a directory to test:

Issue 3: Slow Performance

Symptoms:

• zoxide commands are slow
• Delay when using z command
• High CPU usage

Solutions:

1. Exclude large directories:

2. Check database size:

3. Clean up old entries:

4. Reduce max age:

Issue 4: Wrong Directory Selected

Symptoms:

• z project goes to wrong directory
• Multiple matches but wrong one chosen
• Inconsistent behavior

Solutions:

1. Use interactive mode:

2. List all matches first:

3. Be more specific:

4. Check frequency:

• zoxide learns from usage
• Frequently visited directories get higher priority
• Use directories more often to improve matching

Issue 5: Shell Integration Not Working

Symptoms:

• z command works but doesn't change directory
• Shell hooks not executing
• No automatic directory tracking

Solutions:

1. Verify initialization:

2. Check shell compatibility:

• Make sure you're using a supported shell (bash, zsh, fish, PowerShell)
• Some shells may need different initialization

3. Manual hook setup (if needed):

Diagnostic Steps

Run these commands to diagnose the issue:

Platform-Specific Issues

Linux

Issue: Permission denied

macOS

Issue: Homebrew path not found

Windows

Issue: PowerShell execution policy

Reset zoxide

If nothing works, you can reset zoxide:

Getting Help

If you're still experiencing issues:

1. Check the official zoxide documentation
2. Search GitHub issues
3. Verify your zoxide version is up to date
4. Check system compatibility

Prevention Tips

1. Keep zoxide updated:

2. Regular maintenance:

• Periodically check database size
• Exclude unnecessary directories
• Keep shell configuration clean

3. Test after changes:

• Always test zoxide after modifying shell config
• Verify in new terminal window
• Check both z and zi commands

Related Articles

• zoxide command not found
• Installation guides
• Advanced configuration