Skip to main content
This page covers common issues you might encounter when using Dracula tmux and how to resolve them.

​
Installation issues

Symptoms: The Dracula theme doesn’t appear after installing via TPM or manual installation.Solutions:
  1. Verify plugin installation: 
    # Check if the plugin directory exists
ls ~/.tmux/plugins/tmux
  2. Reload tmux configuration: 
    # Inside tmux, press prefix + I (capital i) to install plugins
# Or reload manually:
tmux source-file ~/.tmux.conf
  3. Check plugin configuration in .tmux.conf: 
    # Make sure you have these lines:
set -g @plugin 'dracula/tmux'

# Initialize TMUX plugin manager (keep at bottom)
run '~/.tmux/plugins/tpm/tpm'
  4. Verify plugin order: The dracula plugin line should come before the run '~/.tmux/plugins/tpm/tpm' line.
Try restarting tmux completely: tmux kill-server then start a new session.
Symptoms: Error messages about TPM not being found when trying to install plugins.Solutions:
  1. Install TPM: 
    git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm
  2. Verify TPM path in config: 
    # Should be at the very end of ~/.tmux.conf
run '~/.tmux/plugins/tpm/tpm'
  3. Install plugins:
    • Reload tmux config: tmux source ~/.tmux.conf
    • Press prefix + I (capital I) to install plugins
Symptoms: Configuration changes not taking effect.Solution:If using $XDG_CONFIG_HOME/tmux/tmux.conf instead of ~/.tmux.conf:
  1. Verify the config location: 
    echo $XDG_CONFIG_HOME
# Should show something like: /home/username/.config
  2. Ensure config exists: 
    ls $XDG_CONFIG_HOME/tmux/tmux.conf
  3. Reload with correct path: 
    tmux source-file $XDG_CONFIG_HOME/tmux/tmux.conf
Dracula works with both ~/.tmux.conf and $XDG_CONFIG_HOME/tmux/tmux.conf.

​
Color and display issues

Symptoms: Status bar shows wrong colors, no colors, or looks broken.Solutions:
  1. Enable true color support: 
    # Add to ~/.tmux.conf
set -g default-terminal "screen-256color"
set -ga terminal-overrides ",*256col*:Tc"
  2. Check terminal emulator support:
    • Ensure your terminal supports 256 colors or true color
    • Test with: echo $TERM
    • Should show something like screen-256color or xterm-256color
  3. Restart tmux completely: 
    tmux kill-server
# Then start a new session
tmux
You may need to detach all sessions and restart tmux for color changes to take effect.
Symptoms: Status bar shows boxes, question marks, or broken characters instead of powerline arrows.Solutions:
  1. Install a Nerd Font or Powerline-patched font:
    • Download from Nerd Fonts
    • Configure your terminal emulator to use the font
  2. Enable powerline in config: 
    set -g @dracula-show-powerline true
  3. Try different powerline symbols: 
    set -g @dracula-show-left-sep 
set -g @dracula-show-right-sep
  4. Disable powerline if fonts unavailable: 
    set -g @dracula-show-powerline false
Symptoms: Icons appear as boxes, question marks, or missing characters.Solutions:
  1. Install a Nerd Font:
    • Download from nerdfonts.com
    • Popular choices: JetBrainsMono Nerd Font, FiraCode Nerd Font, Hack Nerd Font
  2. Configure terminal to use Nerd Font:
    • Update terminal emulator font settings
    • Restart terminal emulator
  3. Fallback to text labels: 
    # Use text instead of icons
set -g @dracula-battery-label "Bat"
set -g @dracula-network-wifi-label "WiFi"
set -g @dracula-cpu-usage-label "CPU"
Symptoms: Widgets are cut off, overlapping, or status bar is too crowded.Solutions:
  1. Reduce number of plugins: 
    # Remove some widgets from the list
set -g @dracula-plugins "battery cpu-usage ram-usage"
  2. Use compact-alt for narrow terminals: 
    set -g @dracula-plugins "compact-alt battery network time"
set -g @dracula-narrow-plugins "compact-alt time"
set -g @dracula-compact-min-width 140
set -g @dracula-config-path "$HOME/.tmux.conf"
  3. Shorten widget labels: 
    set -g @dracula-battery-label false
set -g @dracula-cpu-usage-label ""
  4. Adjust padding: 
    set -g @dracula-left-pad false
set -g @dracula-right-pad false
Symptoms: Widgets with no data still take up space on the status bar.Solution:Hide empty plugins:
set -g @dracula-show-empty-plugins false
This is especially useful for widgets like battery (on desktops) or weather (when location unavailable).

​
Widget-specific issues

Symptoms: Battery widget shows nothing, shows “No Battery”, or displays incorrect information.Solutions:
  1. On desktop PCs (no battery): 
    # Hide the widget when no battery
set -g @dracula-no-battery-label false
# Or use with show-empty-plugins
set -g @dracula-show-empty-plugins false
  2. Battery not detected:
    • Check if battery info is available: cat /sys/class/power_supply/BAT0/capacity
    • On macOS: pmset -g batt
  3. Multiple batteries: 
    set -g @dracula-battery-label "1:\n2:"
set -g @dracula-battery-separator "; "
Compatibility varies by platform. Fully tested on macOS and Linux.
Symptoms: Git widget is empty or shows nothing when in a Git repository.Solutions:
  1. Verify you’re in a Git repository: 
    git status
  2. Check if Git is in PATH: 
    which git
  3. Enable status if disabled: 
    # Make sure this is NOT set to true
# set -g @dracula-git-disable-status true
  4. Show repo when no changes: 
    set -g @dracula-git-show-repo-name true
Symptoms: WiFi connections are detected as ethernet connections.Solution:This is a known issue when iw command is only in root’s PATH:
  1. Check iw availability: 
    which iw
# If this returns nothing, but 'sudo which iw' works, that's the issue
  2. Fix PATH (varies by system):
    • Add /usr/sbin or /sbin to your PATH
    • Or create symlink in user-accessible location
  3. Workaround - use custom labels: 
    set -g @dracula-network-ethernet-label "Connected"
Symptoms: Weather widget displays error message or nothing.Solutions:
  1. Check internet connectivity: 
    curl -I https://wttr.in
  2. Set location manually: 
    set -g @dracula-fixed-location "New York"
  3. Hide errors: 
    set -g @dracula-weather-hide-errors true
set -g @dracula-show-empty-plugins false
Weather data is retrieved from wttr.in. Service availability may vary.
Symptoms: GPU widgets show nothing or incorrect information.Solutions:
  1. Check hardware support:
    • Full support: NVIDIA GPUs on Linux with official drivers
    • Partial: Apple M-chips on macOS, AMD/Intel on Linux
  2. Verify nvidia-smi (for NVIDIA): 
    nvidia-smi
  3. Force GPU detection: 
    set -g @dracula-force-gpu "NVIDIA"
  4. Check permissions (macOS):
    • macOS GPU stats may require sudo privileges
AMD and Intel GPU support is partial. Some metrics may not be available.
Symptoms: Kubernetes widget is empty.Solutions:
  1. Check kubectl configuration: 
    kubectl config current-context
  2. Verify kubectl in PATH: 
    which kubectl
  3. Check kubeconfig: 
    echo $KUBECONFIG
cat ~/.kube/config
Symptoms: Music widgets show nothing or outdated information.Solutions:
  1. Verify required tool is installed: 
    # For spotify-tui
which spt

# For mpc
which mpc

# For playerctl
which playerctl

# For mac-player (macOS only)
# No command needed - uses native APIs
  2. Adjust refresh rate: 
    set -g @dracula-refresh-rate 1
  3. Check if music is playing:
    • Start playback in your music player
    • Widgets may hide when nothing is playing
Symptoms: SSH widget is empty even when connected via SSH.Solutions:
  1. Disable ‘only when connected’ mode: 
    # Make sure this is NOT set to true, or set to false
set -g @dracula-show-ssh-only-when-connected false
  2. Check SSH environment variables: 
    echo $SSH_CONNECTION
echo $SSH_CLIENT
  3. Show port number: 
    set -g @dracula-show-ssh-session-port true
Symptoms: compact-alt widget doesn’t switch between wide and narrow mode.Solutions:
  1. Verify config path is set: 
    set -g @dracula-config-path "$HOME/.tmux.conf"
# Or if using XDG:
set -g @dracula-config-path "$XDG_CONFIG_HOME/tmux/tmux.conf"
  2. Check threshold setting: 
    set -g @dracula-compact-min-width 140
  3. Include compact-alt in narrow plugins: 
    set -g @dracula-narrow-plugins "compact-alt time"
  4. Enable verbose mode to debug: 
    set -g @dracula-compact-alt-verbose true
Never manually set @dracula-narrow-mode - it’s managed by the widget.

​
Performance issues

Symptoms: Widget information appears stale or updates infrequently.Solution:Increase refresh rate:
# Default is 5 seconds
set -g @dracula-refresh-rate 1
Lower values = faster updates but higher CPU usage. Affected widgets: cpu-usage, gpu-info, mpc, spotify-tui, spr, terraform.
Symptoms: tmux process using excessive CPU.Solutions:
  1. Reduce refresh rate: 
    set -g @dracula-refresh-rate 10
  2. Disable expensive widgets:
    • Remove GPU widgets if not needed
    • Remove network-bandwidth if not needed
    • Reduce number of active widgets
  3. Adjust widget-specific intervals: 
    # For network-bandwidth
set -g @dracula-network-bandwidth-interval 5

# For network-ping
set -g @dracula-ping-rate 10

# For synchronize-panes
set -g @dracula-synchronize-panes-refresh-rate 2

​
Platform-specific issues

Known issues on macOS:
  1. GPU widgets require sudo:
    • GPU stats may need elevated privileges
    • Consider using alternative monitoring tools
  2. Battery detection:
    • Usually works well with built-in batteries
    • Uses pmset command
  3. Network detection:
    • WiFi detection uses airport utility
    • Should work on most macOS versions
Dracula tmux is fully compatible with macOS. Tested on tmux 3.1b and later.
Known issues on Linux:
  1. Battery path variations:
    • Battery path might be /sys/class/power_supply/BAT1 instead of BAT0
    • Widget should auto-detect, but may fail on some systems
  2. Network tools:
    • Requires iw for WiFi detection
    • Install: sudo apt install iw (Debian/Ubuntu) or equivalent
  3. GPU detection:
    • NVIDIA: Requires official drivers and nvidia-smi
    • AMD/Intel: Partial support, may need additional packages
Most issues are resolved by installing common system utilities.
FreeBSD status:
FreeBSD compatibility is currently in development. Some widgets may not work as expected.
Known limitations:
  • Battery detection may not work
  • Network detection may need adjustments
  • Some widgets may require FreeBSD-specific tools
Consider testing widgets individually and reporting issues to the GitHub repository.

​
Configuration issues

Symptoms: Configuration changes in .tmux.conf don’t appear after reloading.Solutions:
  1. Reload configuration: 
    tmux source-file ~/.tmux.conf
# Or: prefix + : then type 'source-file ~/.tmux.conf'
  2. Restart tmux completely: 
    tmux kill-server
tmux
  3. Check for syntax errors: 
    # Look for error messages when sourcing
tmux source-file ~/.tmux.conf
  4. Verify option names:
    • Ensure no typos in option names
    • Options are case-sensitive
    • Check hyphen vs underscore
Symptoms: Dracula-specific options have no effect.Solutions:
  1. Check option order: 
    # Dracula options must come BEFORE plugin initialization
set -g @dracula-plugins "battery cpu-usage"
set -g @dracula-show-powerline true

# This must be at the END:
run '~/.tmux/plugins/tpm/tpm'
  2. Reload after TPM install:
    • After installing with prefix + I
    • Reload config again: tmux source-file ~/.tmux.conf
  3. Check for conflicting options:
    • Remove duplicate option definitions
    • Later definitions override earlier ones

​
Getting help

If you’re still experiencing issues after trying these solutions:
  1. Check existing issues:
  2. Gather information:
    • Operating system and version
    • tmux version: tmux -V
    • Terminal emulator
    • Relevant .tmux.conf settings
  3. Create a bug report:
    • Use the bug report template
    • Include steps to reproduce
    • Add screenshots if relevant
    • Describe expected vs actual behavior
The more details you provide, the easier it is to diagnose and fix the issue.
Community resources:

​
Debug mode

For troubleshooting, you can enable verbose output: 
# Run tmux in debug mode
tmux -v

# Or check tmux server info
tmux info
To test widgets individually: 
# Test with minimal config
set -g @dracula-plugins "battery"
# Then try adding widgets one at a time
Create a minimal test configuration to isolate issues and determine if they’re caused by plugin conflicts.

Build docs developers (and LLMs) love

Get started for freeTalk to us