Configuring wezterm (Wez’s Terminal Emulator)

Recently I decided to find the perfect terminal emulator for me and, while I did not actually find perfection I did decide to make wezterm (Wez’s Terminal Emulator) my daily driver. The only major downside is that configuring wezterm requires hacking a Lua file that doesn’t come with with initial download. It doesn’t even come with an example file! In this article I walk through the process I went to configure wezterm to my preferred specifications. This should help you to create your own configuration without feeling lost like I initially did. For me it was worth it since I spend so much time in the terminal and this was the only way I could get one to function exactly as I want.

The following steps will work on FreeBSD, Linux, and probably macOS. On Windows you save the config file in the EXE file, but unless you’re just using Powershell I think you’ll have to do some additional Windows Subsystem for Linux stuff. Sorry, I don’t know much about how any of that works since Windows is the only system I don’t own or use professionally, but the wezterm documentation is pretty good.

Keep in mind that everything I’m doing here is optional. Pick and choose the configurations you like, and once you feel comfortable tinkering with the configuration consult the wezterm documentation to make your own changes. This article is primarily for those who want to get started and don’t want to RTFM.

I’ll continue to play around with wezterm and in the future I’ll make an article about doing some more exotic things with it. This setup is for my MacBook Pro running Manjaro. For my FreeBSD desktop I’ll take advantage of more features and do a writeup on that.

Create Wezterm Configuration File

You have several options when creating a wezterm configuration file. The easiest way is to create a file called .wezterm.lua in your $HOME directory. On Linux this is /home/username and on FreeBSD /usr/home/username. If you plan on going crazy with it you might want to have multiple configuration files that your primary file loads. We’ll do this as I’m going to try and have fun with this thing. In that case, our configuration file is located at

$HOME/.config/wezterm/wezterm.lua.

Note that the file in the home directory starts with a period while the one in the .config folder does not. This means that the file is invisible. In the terminal you can see invisible files/folders by typing ls -a. Most window managers will also have an option to view invisible files/folders.

To start off with, just add the following line to the file and save it:

local wezterm = require 'wezterm'

Locale Settings

If you use zsh, like I do, configuring the locale is especially important as wezterm won’t copy/paste correctly without some tweaking. This tells the system what type of characters we’re using. If you get a bunch of funky characters added, you need to take this step.

On many distros (and macOS), you won’t have to do this as it’s part of the installation process. Unfortunately for me, I had to do it on both FreeBSD and Manjaro. The easiest way to tell whether you need this is to copy and paste some text into the terminal.

FreeBSD

Edit ~/.locale_config to say the following:

me:\
        :charset=iso-8859-1:\
        :lang=en_US.ISO8859-1:

Use the appropriate country code/language for your location.

# localectl set-locale LANG=en_US.UTF-8

Arch-Based Distros

If you don’t have systemd or you want to do this manually, edit /etc/locales.gen to uncomment the line that says LANG=en_US.UTF-8 (or the appropriate line for your country/language).

Debian-Based Distros

Similar to the above, if your distro lacks systemd you can do this manually. Add the following to /etc/profile/:

: "${LANG:=en_US.iso88591}"; export LANG

Use the appropriate country code/language for your location.

Enable Combining Characters (zsh only)

If you use zsh, add the following line to ~/.zshrc:

setopt COMBINING_CHARS

Set Font

Now we can begin some customizations. Let’s set a font. Choose from any font installed on your system. Place the following code in your wezterm.lua file:

return {
        font = wezterm.font 'Space Mono for Powerline',
        font_size = 10.5,
}

Note that wezterm will change as soon as you save this file. If you want to tinker with several different options, you can just keep the file and the terminal open and save your changes to see them instantly take effect.

Additional Font Modifications

I’m not using any of these in my configuration, but you can also make the following tweaks (values after equal sign can be adjusted):

• cursor_blink_rate = 800,
• cursor_thickness = 2px,
• line_height = 2.5px,
• underline_position = 1px,
• underline_thickness = 2px,

There are more tweaks available. Consult the documentation.

Set Color Scheme

We now have the font the way we’d like it, but how about a color scheme? Wezterm allows you to manually set your color scheme, but that is tedious and wezterm comes with 735 predefined color schemes. You should be able to find something from that extensive list that matches what you have in mind.

On the next line of our configuration file (before the last bracket, after the font_size line), add the following line:

color_scheme = "Banana Blueberry"

Replace “Banana Blueberry” with the color scheme of your choice.

Window Opacity

You can reduce the window opacity with the following line:

window_background_opacity = .85,

The value ranges from 0.0 (fully transparent) to 1.0 (fully opaque).

Enable Scrollbar

Why doesn’t wezterm come with a scrollbar by default? I don’t know, but I prefer one. Add the following line (unless specified, going forward these additions will all be added to the “return” section before the final bracket).

enable_scroll_bar = true,

SSH

For this setup, I’m going to put this ssh configurations in a separate file. This is just to keep things better organized. First, create a new folder in the $HOME/.config/wezterm folder. I called mine extra but you can call yours whatever you want. In the extra folder, we create a new lua file. I called mine ssh.lua. Let’s add a basic ssh configuration:

return {
   {
      -- This name identifies the domain
      name = 'SERVER NAME',
      -- Server IP
      remote_address = 'YOUR IP HERE',
      -- Server Username
      username = 'YOUR USERNAME HERE',
      -- Multiplexing is the default; to allow it, delete the following line
      multiplexing = 'None',
  },
   {
      name = 'SERVER NAME',
      remote_address = 'YOUR IP HERE',
      username = 'YOUR USERNAME HERE',
      multiplexing = 'None',
  },
}

The SERVER NAME can be whatever you want. It’s just a variable to call the settings below it. If you use an SSH key to connect to your sever and it’s in the default $HOME/.ssh/ folder, it will automatically be used. If you store your keys in a different location, edit /etc/ssh/ssh_config and make the appropriate changes. Also, if you use a port other than 22, you will have to specify this in /etc/ssh/ssh_config.

Now we need to tell our main configuration file to read our ssh.lua file. At the top (above return) of the main configuration, add the following line:

local ssh_domains = require('extra.ssh')

Remember that extra was the name of the folder I made and ssh.lua was the name of the file. If you used different names you will need to change “extra” and/or “ssh.” Now, in the main part of the file, (after return and before the last curly brace), add the following line:

ssh_domains = ssh_domains,

To connect to an SSH domain, type the following in the terminal, replacing YOUR SERVER NAME with the value you created in the config file:

# wezterm connect YOUR SERVER NAME

Some Basic wezterm Tips

• The wezterm command provides additional functionality; type wezterm help to see a complete list
• Right click the new tab button [+] to bring up a menu
• As I use wezterm more I’ll add to this lsit