Skip to main content
WezTerm supports both implicit and explicit hyperlinks, allowing you to click URLs and create custom clickable patterns that integrate with your workflow. Implicit hyperlinks are automatically generated by matching patterns in terminal output. WezTerm includes default rules for URLs and allows you to define custom patterns.

​
Default URL Matching

By default, WezTerm automatically detects and makes URLs clickable:
  • http:// and https:// URLs
  • file:// URLs
  • mailto: links
Simply click any detected URL to open it in your default browser. Create clickable patterns for your specific workflow:
Task Numbers
local wezterm = require 'wezterm'
local config = {}

-- Start with the defaults
config.hyperlink_rules = wezterm.default_hyperlink_rules()

-- Make task numbers clickable
-- Matches T123 or t123 and links to task tracker
table.insert(config.hyperlink_rules, {
  regex = [=[\b[tt](\d+)\b]=],
  format = 'https://example.com/tasks/?t=$1',
})

return config
Automatically link GitHub repository references:
GitHub Repos
local wezterm = require 'wezterm'
local config = {}

config.hyperlink_rules = wezterm.default_hyperlink_rules()

-- Make username/project paths clickable
-- Matches patterns like: wezterm/wezterm or "nvim-treesitter/nvim-treesitter"
table.insert(config.hyperlink_rules, {
  regex = [=[["']?([\w\d]{1}[-\w\d]+)(/){1}([-\w\d\.]+)["']?]=],
  format = 'https://www.github.com/$1/$3',
})

return config

​
JIRA Issues

JIRA Links
table.insert(config.hyperlink_rules, {
  regex = [=[\b([A-Z]+-\d+)\b]=],
  format = 'https://jira.company.com/browse/$1',
})

​
Pull Request Numbers

PR Numbers
table.insert(config.hyperlink_rules, {
  regex = [=[\bPR\s*#?(\d+)\b]=],
  format = 'https://github.com/yourorg/yourrepo/pull/$1',
})

​
Pattern Matching

Hyperlink rules use regular expressions with capture groups:
  • regex - The pattern to match
  • format - The URL template where $1, $2, etc. are replaced with captured groups
The first matched regex group is captured in $1, the second in $2, and so on.

​
Example: Multiple Capture Groups

Docker Image Tags
table.insert(config.hyperlink_rules, {
  regex = [=[\b([\w-]+)/([\w-]+):(\w+)\b]=],
  format = 'https://hub.docker.com/r/$1/$2/tags?name=$3',
})
This matches patterns like library/nginx:latest and creates a link to Docker Hub. WezTerm supports the Hyperlinks in Terminal Emulators specification, which allows programs to emit hyperlinks without showing the URL. From the command line:
Output Hyperlink
printf '\e]8;;http://example.com\e\\This is a link\e]8;;\e\\\n'
This displays “This is a link” as clickable text that opens http://example.com.

​
Format Specification

The escape sequence format is: 
\e]8;;{URL}\e\\{display text}\e]8;;\e\\
  • First part: \e]8;;{URL}\e\\ - Starts the hyperlink
  • Middle: {display text} - The visible text
  • Last part: \e]8;;\e\\ - Ends the hyperlink

​
Script Example

Bash Function
#!/bin/bash

# Function to create a hyperlink
hyperlink() {
  local url="$1"
  local text="$2"
  printf '\e]8;;%s\e\\%s\e]8;;\e\\' "$url" "$text"
}

# Usage
hyperlink "https://wezterm.org" "Visit WezTerm"
echo

​
Advanced Configuration

​
Combining Rules

local wezterm = require 'wezterm'
local config = {}

-- Start with defaults
config.hyperlink_rules = wezterm.default_hyperlink_rules()

-- GitHub issues
table.insert(config.hyperlink_rules, {
  regex = [=[\b[Ii]ssue\s*#?(\d+)\b]=],
  format = 'https://github.com/myorg/myrepo/issues/$1',
})

-- JIRA tickets
table.insert(config.hyperlink_rules, {
  regex = [=[\b([A-Z]+-\d+)\b]=],
  format = 'https://jira.example.com/browse/$1',
})

-- File paths (local file:// URLs)
table.insert(config.hyperlink_rules, {
  regex = [=[\b(/[\w\-./]+)\b]=],
  format = 'file://$1',
})

return config
By default, clicking a hyperlink opens it in your system’s default browser. You can customize this behavior:
Custom Link Handler
config.hyperlink_rules = wezterm.default_hyperlink_rules()

-- The hyperlink will be opened with the default browser
-- You can override this in your shell config or window manager

​
Keyboard Navigation

Use Quick Select mode (Ctrl+Shift+Space) to quickly select and open visible hyperlinks without using the mouse.

​
Best Practices

1

Start with defaults

Always begin with wezterm.default_hyperlink_rules() to preserve standard URL matching.
2

Test your patterns

Use a regex testing tool to verify your patterns match correctly before adding them.
3

Order matters

Rules are evaluated in order. Place more specific rules before general ones.
4

Avoid conflicts

Ensure your custom patterns don’t conflict with default URL patterns.

​
Troubleshooting

  1. Check that your pattern is correctly escaped (Lua string escaping)
  2. Verify the regex matches your expected text
  3. Ensure the rule is added to config.hyperlink_rules

​
Wrong URL Generated

  1. Verify capture groups are in the correct order
  2. Check that $1, $2 etc. reference the right groups
  3. Test the format string with sample matches

​
Performance Issues

  • Complex regex patterns can slow down rendering
  • Limit the number of rules for better performance
  • Use specific patterns rather than overly broad matches