Skip to main content
Having trouble with Glow? This guide covers common issues and their solutions.

​
Style Not Rendering Correctly

​
Problem: Colors or formatting look wrong

Solution: Glow attempts to auto-detect your terminal’s background color. You can manually specify a style: 
glow -s dark README.md    # For dark backgrounds
glow -s light README.md   # For light backgrounds
Permanent fix: Set your preferred style in the config file: 
glow config
Then set the style: 
style: "dark"  # or "light"

​
Problem: Custom style not loading

Solution: Ensure your custom JSON stylesheet exists and the path is correct: 
glow -s /path/to/mystyle.json README.md
Verify the file path is absolute or use the full path. Check that the JSON is valid using a JSON validator.

​
TUI Not Launching

​
Problem: TUI mode doesn’t start

Cause: When you provide a file argument, Glow uses CLI mode by default. Solution: Explicitly enable TUI mode: 
glow -t README.md    # Force TUI mode
glow                 # TUI mode in current directory
glow /path/to/dir    # TUI mode in specific directory

​
Problem: TUI crashes or displays incorrectly

Solution: Check your terminal emulator compatibility:
  • Ensure your terminal supports ANSI colors
  • Try a different terminal emulator (kitty, iTerm2, Alacritty, etc.)
  • Update your terminal emulator to the latest version
  • Check if you’re using a terminal multiplexer (tmux/screen) and ensure it’s configured for 256 colors

​
Terminal Compatibility Issues

​
Problem: Characters rendering as boxes or question marks

Cause: Your terminal may not support Unicode or is using an incorrect locale. Solution:
  1. Check your locale: 
    echo $LANG
  2. Set UTF-8 locale if needed: 
    export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8
  3. Ensure your terminal font supports Unicode characters

​
Problem: Colors not displaying in tmux

Solution: Configure tmux for 256 colors. Add to ~/.tmux.conf: 
set -g default-terminal "screen-256color"
Or use: 
set -g default-terminal "tmux-256color"
Then restart tmux or reload the config: 
tmux source-file ~/.tmux.conf

​
Configuration File Problems

​
Problem: Config file not found or not loading

Solution: Glow looks for config files in platform-specific locations:
  • Linux/BSD: ~/.config/glow/glow.yml
  • macOS: ~/Library/Application Support/glow/glow.yml
  • Windows: %APPDATA%\glow\glow.yml
Create the config file: 
glow config
Or specify a custom config file: 
glow --config /path/to/config.yml

​
Problem: Configuration changes not taking effect

Solution:
  1. Verify the config file path: 
    glow --help | grep config
  2. Ensure the YAML syntax is correct (proper indentation, no tabs)
  3. Command-line flags override config file settings - remove conflicting flags

​
Problem: Invalid config file format error

Cause: Glow only supports .yml or .yaml extensions. Solution: Rename your config file to glow.yml: 
mv glow.config glow.yml

​
Permission Errors

​
Problem: Permission denied when reading files

Solution:
  1. Check file permissions: 
    ls -la README.md
  2. Ensure you have read access to the file: 
    chmod +r README.md

​
Problem: Can’t create config directory

Solution: Manually create the config directory: 
# Linux/macOS
mkdir -p ~/.config/glow

# Windows (PowerShell)
New-Item -ItemType Directory -Path "$env:APPDATA\glow"

​
GitHub/GitLab Fetching Issues

​
Problem: Can’t fetch README from GitHub/GitLab

Solution:
  1. Check your internet connection
  2. Verify the repository exists and is public
  3. Try the full URL: 
    glow https://github.com/username/repo

​
Problem: Rate limit errors from GitHub

Solution: Authenticate with GitHub to increase rate limits. Set up a personal access token and use environment variables or GitHub CLI authentication.

​
Pager Issues

​
Problem: Pager not working

Solution: Set your $PAGER environment variable: 
export PAGER="less -r"
glow -p README.md
Or specify in config: 
pager: true

​
Performance Issues

​
Problem: Slow rendering with large files

Recommendations:
  • Use CLI mode instead of TUI for very large files
  • Reduce the word-wrap width: 
    glow -w 80 largefile.md
  • Disable line numbers in TUI mode

​
How to Report Bugs

If you’ve tried the solutions above and still have issues, please report a bug:
  1. Check existing issues: https://github.com/charmbracelet/glow/issues
  2. Gather information:
    • Glow version: glow --version
    • Operating system and version
    • Terminal emulator and version
    • Shell (bash, zsh, fish, etc.)
    • Locale: echo $LANG
  3. Enable debug logging: 
    export GLOW_DEBUG=1
glow your-file.md 2> glow-debug.log
  4. Create a minimal reproduction:
    • Simplify the markdown file that causes the issue
    • Note the exact command that triggers the problem
  5. Submit the issue: https://github.com/charmbracelet/glow/issues/new

​
Getting Help

Still stuck? Reach out to the community:

Build docs developers (and LLMs) love

Get started for freeTalk to us