Quick Start

Get up and running with WezTerm in 5 minutes

Launch WezTerm

After installing WezTerm, launch it from your applications menu or command line:

macOS

open -a WezTerm

WezTerm will start with its default configuration, providing a functional terminal immediately.

Create Your Configuration File

1. Create .wezterm.lua

   Create a configuration file in your home directory:

   macOS/Linux

   touch ~/.wezterm.lua
   
2. Add basic configuration

   Open ~/.wezterm.lua in your text editor and add:

   -- Pull in the wezterm API
   local wezterm = require 'wezterm'
   
   -- This will hold the configuration
   local config = wezterm.config_builder()
   
   -- Basic configuration
   config.font = wezterm.font 'JetBrains Mono'
   config.font_size = 12.0
   
   config.color_scheme = 'Tokyo Night'
   
   config.window_padding = {
     left = 8,
     right = 8,
     top = 8,
     bottom = 8,
   }
   
   -- Return the configuration to wezterm
   return config
   
3. Reload configuration

   WezTerm automatically reloads when you save the configuration file. You’ll see your changes applied immediately.

Essential Features

Tabs and Panes

Create and navigate multiple terminals within one window:

Action	macOS	Linux/Windows
New tab	Cmd+T	Ctrl+Shift+T
Close tab	Cmd+W	Ctrl+Shift+W
Next tab	Cmd+Shift+]	Ctrl+Tab
Previous tab	Cmd+Shift+[	Ctrl+Shift+Tab
Split horizontal	Cmd+Shift+"	Ctrl+Shift+Alt+"
Split vertical	Cmd+Shift+%	Ctrl+Shift+Alt+%

Search Scrollback

Press Ctrl+Shift+F to search through your terminal history.

Copy and Paste

• Select text with your mouse, it’s automatically copied
• Paste with Ctrl+Shift+V (Linux/Windows) or Cmd+V (macOS)

Customize Your Setup

Choose a Font

Browse available fonts:

wezterm ls-fonts

Then configure your preferred font:

config.font = wezterm.font 'Fira Code'
config.font_size = 13.0

Pick a Color Scheme

WezTerm includes 700+ color schemes. Some popular options:

-- Dark themes
config.color_scheme = 'Tokyo Night'
config.color_scheme = 'Catppuccin Mocha'
config.color_scheme = 'Dracula'
config.color_scheme = 'Gruvbox Dark'
config.color_scheme = 'Nord'

-- Light themes
config.color_scheme = 'Tokyo Night Day'
config.color_scheme = 'Catppuccin Latte'

Adjust Window Size

config.initial_cols = 120
config.initial_rows = 30

Enable Transparency

config.window_background_opacity = 0.95
config.macos_window_background_blur = 10  -- macOS only

Example Configuration

Here’s a complete starter configuration:

local wezterm = require 'wezterm'
local config = wezterm.config_builder()

-- Font configuration
config.font = wezterm.font {
  family = 'JetBrains Mono',
  weight = 'Medium',
}
config.font_size = 12.0

-- Color scheme
config.color_scheme = 'Tokyo Night'

-- Window appearance
config.window_background_opacity = 0.95
config.window_padding = {
  left = 8,
  right = 8,
  top = 8,
  bottom = 8,
}

-- Tab bar
config.hide_tab_bar_if_only_one_tab = true
config.use_fancy_tab_bar = false

-- Scrollback
config.scrollback_lines = 10000

-- Disable audible bell
config.audible_bell = 'Disabled'

return config

Next Steps

Configuration Guide

Learn about all configuration options

Key Bindings

Customize keyboard shortcuts

Features

Explore advanced features

Lua API

Deep dive into Lua configuration

Troubleshooting

Configuration not loading?

Check the configuration file location:

wezterm show-config

Look for syntax errors in the output.

Font not displaying correctly?

List available fonts:

wezterm ls-fonts

Verify your chosen font is installed and available.

Colors look wrong?

Ensure your color scheme name is correct:

wezterm show-config | grep color_scheme

Browse available schemes in the WezTerm source or documentation.

Press Ctrl+Shift+L to show the debug overlay with detailed configuration information.