To enable hyperlinks in your Tmux configuration, you must set the allow-passthrough option to on and configure terminal capabilities. This allows escape sequences generated by applications like Git or VS Code to pass through the Tmux layer directly to your host terminal emulator. Without these settings, hyperlink click events are intercepted or stripped, breaking navigation.
Understanding Terminal Hyperlink Support
Modern terminal emulators support clickable text links using specific OSC (Operating System Command) escape sequences. These sequences typically follow the format8;params;uri48;; . When an application outputs this sequence, the terminal renders the text as a hyperlink. However, when you run an application inside a Tmux session, the terminal emulator does not see the raw output from the inner application. Instead, it sees the output from the Tmux process itself.
By default, Tmux acts as a filter that strips or modifies certain control characters to maintain its own internal state management. This behavior prevents hyperlink sequences from reaching the outer terminal emulator. To fix this, you need to tell Tmux to stop filtering these specific passthrough sequences. This is primarily achieved through the terminal-overrides and allow-passthrough options.
Configuring the Tmux Config File
The most reliable way to enable hyperlinks is to edit your~/.tmux.conf file. You should add specific lines that instruct Tmux to allow the passage of these escape codes. First, ensure that your Tmux version supports this feature. Most modern versions (3.2 and above) handle this well, but older versions may require more complex workarounds.
Add the following line to your config file:
set -g allow-passthrough on
ESC ] 8 ;, which is the standard prefix for hyperlinks. If you are using a newer version of Tmux, this single line might be sufficient for basic functionality. However, some terminals require additional capability flags to correctly interpret the link data.
For broader compatibility, especially with terminals like iTerm2, Alacritty, or Windows Terminal, you may also need to update the terminal-overrides setting. This setting maps specific terminal type strings to their capabilities. Add the following to your config:
set -ga terminal-overrides ",xterm-256color:Tc"
Tc flag enables true color support, which often accompanies hyperlink support in modern terminal implementations. While not strictly required for all hyperlink types, it ensures that the visual rendering context is compatible with advanced features. After adding these lines, save the file and reload your Tmux configuration by running :source-file ~/.tmux.conf inside a Tmux session, or restart your terminal entirely.
Verifying the Setup
Once the configuration is applied, you can verify that hyperlinks are working correctly. Open a new Tmux window and launch a command that generates hyperlinks. The most common tool for testing this is Git. Run a command likegit log --oneline or view a file with less if it contains URL references.
In many cases, Git will automatically convert commit hashes or URLs into clickable links if the terminal supports it. Click on one of these links. If the setup is correct, your system's default web browser should open immediately. If nothing happens, the sequence was likely still filtered by Tmux.
You can also test with a simple echo command to generate a raw hyperlink sequence:
echo -e "\033]8;;https://example.com\007Example Link\033]8;;\007"
https://example.com with any valid URL. If clicking the text opens the page, your Tmux configuration is successfully passing through the hyperlink data. If it fails, check that you have restarted the Tmux server or reloaded the config file after making changes.
Troubleshooting Common Issues
If hyperlinks still do not work after applying the settings, consider the following potential causes. First, verify your Tmux version. Older versions may not supportallow-passthrough natively. You can check your version by running tmux -V. If you are on an outdated version, consider upgrading Tmux via your package manager.
Second, ensure that your host terminal emulator actually supports hyperlinks. Not all terminal applications implement this feature. Popular terminals like iTerm2, Alacritty, WezTerm, and Windows Terminal have robust support, while some lightweight or legacy terminals may not. Check your terminal's documentation to confirm hyperlink support.
Third, some applications inside Tmux may not generate hyperlink sequences even if the terminal supports them. For example, older versions of Vim or specific CLI tools might not output the necessary escape codes. In such cases, enabling hyperlinks in Tmux will not help unless the inner application is configured to produce them.
For users who frequently switch between different environments, you might find it useful to adjust other Tmux behaviors. For instance, managing pane layouts can improve visibility when debugging complex output. See How to Change Tmux Tile Layout to Arrange 8 Panes into 3x3 Instead of 4x2 for tips on optimizing your workspace structure. Additionally, if you use custom keybindings, ensure they do not conflict with hyperlink interactions. Reviewing Keybind Tmux in Alacritty: A Tech Support Guide can help you avoid binding keys that interfere with mouse events or special sequences.
Frequently Asked Questions
Does this work with SSH sessions?
Yes, hyperlinks work over SSH as long as both the local and remote terminals support passthrough. Ensure that the remote server's Tmux config also has allow-passthrough on. The escape sequences travel through the SSH tunnel intact if Tmux on the remote side is configured correctly.
Why do my links look underlined but not clickable?
This usually means the terminal recognizes the escape sequence but does not have the mouse protocol enabled for link detection. Some terminals require explicit mouse mode activation. Check your terminal settings to ensure that "Enable Mouse Mode" or similar options are turned on for hyperlink interaction.
Can I disable hyperlinks for specific panes?
Tmux applies allow-passthrough globally to the session. You cannot easily disable it for just one pane without affecting others. However, you can create separate sessions with different configurations if you need distinct behaviors for different workflows.
What if I am using an old version of Tmux?
If your version is below 3.2, allow-passthrough may not exist. You would need to upgrade Tmux or use terminal-specific overrides in terminal-overrides to mimic the behavior. Upgrading is the recommended path as older versions lack many performance and compatibility improvements.
Do IDEs inside Tmux support hyperlinks?
Most modern IDEs like VS Code or JetBrains products support hyperlinks within their integrated terminals. If you run them inside Tmux, the previous configuration steps apply. Ensure the IDE's terminal integration is set to pass through escape codes rather than handling them internally.