How to Obsessively Tune WezTerm

(rashil2000.me)

101 points | by todsacerdoti 20 hours ago ago

61 comments

  • technojamin 17 hours ago

    I love WezTerm! In the author's spirit of obsessive tweaking, here's a completely inconsequential configuration change I made.

    By default, WezTerm doesn't have a scrollbar, but you can easily enable it with:

      config.enable_scroll_bar = true
    
    But now you always have a scrollbar, just a big line on the side when there's no scrollback or you're in alternate screen mode. Horrible! So, here's an event handler that will automatically hide the scrollbar when not needed, giving it the same behavior as scrollbars in modern applications:

      -- Hide the scrollbar when there is no scrollback or alternate screen is active
      wezterm.on("update-status", function(window, pane)
        local overrides = window:get_config_overrides() or {}
        local dimensions = pane:get_dimensions()
    
        overrides.enable_scroll_bar = dimensions.scrollback_rows > dimensions.viewport_rows and not pane:is_alt_screen_active()
    
        window:set_config_overrides(overrides)
      end)
    
    And that kinda sums up the development philosophy of WezTerm. It has basically all the building blocks you'd ever need with nice APIs. It's set up quite usably by default, but anything that's missing you can probably implement yourself.
    • rashil2000 4 hours ago

      That's pretty nice! Thanks for the tip, I applied it to my config as well.

    • bbkane 17 hours ago

      Thanks, I've copied that into my config!

    • hdjrudni 10 hours ago

      Now I want more scrollbars. One per pane please. Doesn't seem to be an option.

  • lawrencegripper 18 hours ago

    Wezterm is a lot of fun. I played around with notifications and copy/paste which work even through ssh back to the host.

    https://blog.gripdev.xyz/2025/01/08/wezterm-easily-copy-text...

    • natrys 16 hours ago

      Wasn't aware of user-var-changed, cool write-up!

      I had used urxvt forever before and the simple solution that works (even for ssh e.g.) is to ring the terminal bell, and urxvt just sets the window urgency hint upon that. I just do that in shell prompt unconditionally because if it's triggered in a focused window, then nothing happens. But if it's from a different workspace, I get this nice visual cue in my top bar for free.

      But features like setting urgency isn't available in wezterm (understandable, as it's not a cross-platform thing). I could patch that in the source, but the Emacser in me chose to do something more unholy. By default Lua is started in safe mode, which means loading shared C module is forbidden. I disabled that, and now use a bunch of missing stuff written in Rust and Zig interfaced with cffi. Don't recall ever having a crash so I am surprised by some of the other comments.

    • binary132 15 hours ago

      Yeah, I use wezterm for remote editing at work because it has the best support for chords over ssh, and everything basically just works out of the box. Really convenient

  • CGamesPlay 6 hours ago

    I recently made a list of "features I actually use in iTerm 2", while I was looking at alternatives that were cross-platform. The extensibility that WezTerm and others (Kitty takes the cake, it seems) looks promising, but after reading the docs, I don't think any of the trendy terminal emulators can do these two specific features:

    1. Custom escape sequences that trigger my own code. iTerm 2 and Kitty support this (Kitty calls them "kittens"), but I don't think any other terminal emulators do. WezTerm appears not to. User variables do come close, but are not quite the same, since a user variable is "declarative" and this behavior is "imperative".

    2. Show timestamps for each scrollback line. This is a feature you don't miss until you need it, but I use it, for example, to match log output timestamps to the time I ran a command in mysql console on a remote server.

    I don't really care about streaming 134.55 MB/s of text to my terminal emulator; I do care about features that make me productive.

    • FuckButtons 2 hours ago

      > I don't really care about streaming 134.55 MB/s of text to my terminal emulator; I do care about features that make me productive.

      On two occasions, dumping a real time data stream to std out has actually been a useful debugging technique for me, your domain might be quite different from mine, but I wouldn’t discount that performance is a feature in itself.

  • ratmice 15 hours ago

    The thing I love most about wezterm is the `wezterm cli list --format json`, and being able to get various values like the cwd of any terminal by window id. While I don't much tweak my actual wezterm config at all. I use that a lot for various scripts to launch other terminals/file managers in the same directory as the currently active terminal...

  • hdjrudni 10 hours ago

    I'm having two issues with WezTerm.

    1. When I split the terminal in 2 (left/right) and drag the slider around it glitches out and lags. On Linux at least. Like, I can release my mouse button and it'll just glitch back and forth between its old position and new position for a minute before settling down. (It also mangles any text that was already on the screen, but I'm guessing that's an artifact of the underlying shell, not wezterm)

    2. I have a bunch of hyperlink regexes configured, but if there's a very long URL being displayed, WezTerm breaks the link. It's like it doesn't want to match URLs across multiple lines except the weird part is that the URL is literally only one line, it's WezTerms wrapping that makes it take multiple lines. So the regex is matching on displayed lines not on \ns, which is weird and breaks me constantly.

    Other than those two things, it's pretty good.

    Another issue I have with all terminals I've found so far is sometimes a program will just hang and no amount of Ctrl+C will kill it. And it drives me bonkers. I don't understand why the terminal can't take over and kill the entire shell and respawn it if it has to. In Wez I have to kill the pane or close the whole app. I tried digging in the Lua if I could "respawn pane" with a hotkey or something but I couldn't figure anything out that would keep my split-pane positioning.

  • gandreani 19 hours ago

    I get the error `Your store is blocked` when trying to load the images

    • level87 19 hours ago

      Same

      • bbkane 17 hours ago

        Me too- these images are very important to the blog post, I wish I could see them

        • rashil2000 16 hours ago

          Sorry, I ran out of the free Blob Storage transfer quota, should be fixed now

  • bbkane 17 hours ago

    I love WezTerm! The cross-platform config is easy to version control (unlike iTerm2) and I've added a couple integrations that I use constantly:

    The first is hashing the working directory / (or remote hostname if I'm SSH'd into a host) to set tab title colors- much easier to find the right tab that way.

    The second is writing a script to open tabs with in a certain order and set their titles. I don't use tmux, but this let's me recreate my preferred layout for projects quite easily.

    See https://github.com/bbkane/dotfiles/tree/master/wezterm if any of this sounds useful to you!

  • weinzierl 18 hours ago

    WezTerm is great. When I switched back to Linux from Apple there were very few things I missed. iTerm2 was one of them, but since I found WezTerm I am pretty happy.

    I tried to use it on Windows as well but unfortunately the Antivirus freaks out on it. When I looked into it it was because of a small utility `strip-ansi-escapes` which is so simple that even I could see that it is a false positive. I tried to report it to Microsoft and other Antivirus companies with some success but in the end I gave up an this Sisyphus task.

    • keithnz 18 hours ago

      I have zero problem with WezTerm on Windows.

      • weinzierl an hour ago

        Depends on the antivirus you use. Try it with Virustotal and you'll see that it is not only the usual one or two false positives and this number already decreased because I reported it to all vendors. Unfortunately not all of them are responsive.

  • spoaceman7777 17 hours ago

    Wezterm was great, but I had to stop using it recently because it keeps crashing immediately (across two different computers) on CachyOS/Arch :/

    It's just broken on KDE permanently I guess :/ There have beem tickets about it, and there is an AUR repo with a patch that used to fix it... but :/

    Was already worried about the project given that it hasn't seen a new release in quite a long time. Got the feeling that the maintainer has mostly moved on.

    • resonious 17 hours ago

      It's been almost a year for me now but I had also stopped using it due to crashes. And since it shares a process for all your windows, it would close all my windows which just drove me nuts after awhile.

      Though for me, I only wanted the absolute bare minimum, which Alacritty covers. I was sad to lose ligatures, but Alacritty is stable and very fast.

      • WD-42 16 hours ago

        Ghostty replaced wezterm for me, plus it supports ligatures and is just as fast as alacritty.

    • doom2 5 hours ago

      I'm also suffering this on macOS. I can get through an entire work day, but when I close the laptop for the night and come back the next day, wez has crashed and I don't know why.

    • johnny22 16 hours ago

      > Was already worried about the project given that it hasn't seen a new release in quite a long time

      IIRC the maintainer was moving countries. Not saying that's the main or only reason, but it is likely a factor.

  • TheRoque 9 hours ago

    I wish I could use Wezterm because it's the only true cross platform terminal with nice features, but on Windows it's buggy, when moving the terminal from one screen to another, when they have different scaling. It's the only bug preventing me from using it.

  • dmd 16 hours ago

    This post would be a lot better if all the images weren't broken.

    • rashil2000 16 hours ago

      Sorry, I ran out of the free Blob Storage transfer quota, should be fixed now

  • 0cf8612b2e1e 20 hours ago

    Could someone sell me on one of these alternative terminals (kitty, ghostty, wez, etc)? There is probably something I am missing not using GPU backed rendering, but I don’t know what I don’t know.

    • tcoff91 18 hours ago

      I really love the following things that I can do with kitty:

      - Access the scrollback buffer in neovim

      - Access the last command output in neovim

      - Animated cursor trails. It sounds dumb at first but I find that when sharing my screen, the cursor trails help other people keep track of my cursor when using neovim.

      Here are my configs to quickly load @screen_scrollback or @last_cmd_output in neovim

      map kitty_mod+z launch --stdin-source=@screen_scrollback --type=overlay /bin/zsh -c "nvim +$ +'nnoremap q ZQ'"

      map kitty_mod+v launch --stdin-source=@last_cmd_output --type=overlay /bin/zsh -c "nvim +$ +'nnoremap q ZQ'"

      • alwillis 17 hours ago

        Gotta give a shoutout regarding Ghostty [1]. I keep switching terminal apps; I'm on an iTerm2 kick right now… but I used Ghostty for a while and it's pretty damn cool.

        Anecdotally, it feels the fastest to me. Also GPU-accelerated and super configurable. It's amazing how a guy (Mitchell Hashimoto)[2] leaves the company he co-founded before it was sold to IBM.

        [1]: https://ghostty.org

        [2]: https://www.youtube.com/watch?v=l_qY2p0OH9A

        • tcoff91 15 hours ago

          Can ghostty pipe the scrollback buffer to nvim?

      • throwaway290 16 hours ago

        You can get cursor trail on any terminal these days...

        • tcoff91 15 hours ago

          Can you access the scrollback buffer in nvim?

    • rao-v 19 hours ago

      All I want is terminals to share config across MacOS, Linux and ideally Windows and have great support for SSHing into low end boxes with some minimal persistence solution like tmux on them. In an ideal world I would not have to think about mouse capture and scroll modes, they’d work seamlessly across my device and the devices I’m SSHed into.

      It shocked me when I got back into playing with multiple machines after over a decade that this mostly still does not exist.

      Instead we’re finally doing gpu rendering (which is amazing but … surprising for this to be the 2025 topic du jour?)

    • andai 19 hours ago

      I tried a few of them and they were all way slower than xfce4-terminal. So I just kept using that.

      I don't really dump megabytes of text into the terminal, they might have an edge there? (I found that xterm is much faster than xfce4-terminal for that.)

    • zeppelin101 18 hours ago

      I have a very silly primary reason for preferring the Kitty terminal - I configured it to look very minimalistic and compact. It doesn't even have the customary app titlebar at the top. The other benefit is that it's actually a lot faster to start up than Terminal.app when you first invoke it. I know iTerm2 is really well-liked, but to me, it gave the "Breakin' 2: Electric Boogaloo" vibes.

    • lordgroff 19 hours ago

      Kitty and wez both have the ability to present graphics on the terminal which may sound like a solution in search of a problem, but once you start using the capability, it's hard to live without it.

      Wez is also cross platform so I get to use it on my Linux and Mac and my (Ugh) Windows work machine. Configuration being done in Lua is also something I quite like, but your mileage may vary on that one.

      • theshrike79 6 hours ago

        This is kinda mind-blowing when combined with yazi[0] for example. You can browse a directory with images or videos on your terminal and see previews of both.

        [0] https://yazi-rs.github.io/features

      • daotoad 17 hours ago

        I was using Wezterm because of the cross platform and the lua config (let's me reuse my mad lua skilz from keeping my nvim config).

        The thing that made me switch to Ghostty was the image support in wez didn't play well with tmux.

        After testing wez, kitty, and Ghostty, I ended up going with Ghostty.

        I do miss the idea of the whole lua config thing, but since I never did anything with it, I can't treat that as a practical concern.

    • prmph 19 hours ago

      All I know is that on MacOS iTerm2 is unmatched. Every few months I go in search of something similar to it (as a backup), and every single time, after trying countless terminals, I give up. The closest I've found is WezTerm, and even that is a pale shadow of Iterm2

      • gsinclair 19 hours ago

        I switched from iTerm to WezTerm and haven’t looked back. It feels faster and it’s simpler to configure. I only have a basic use case, though, as tmux does all the heavy work for me. People with an appetite for more features might legitimately prefer iTerm, but I can’t endorse the comment “pale shadow of iTerm” for all use cases.

      • theshrike79 6 hours ago

        I use 2-5 different macs semi-regularly.

        What killed iTerm2 for me was the fact that syncing settings between machines with chezmoi was next to impossible.

        With Wezterm it's just Lua code, easy to diff and easy to apply.

    • alwillis 17 hours ago

      > Could someone sell me on one of these alternative terminals (kitty, ghostty, wez, etc)?

      * They're very fast and the scrolling is very smooth, especially on a 120 Mhz (ProMotion) refresh rate on MacBook Pros.

      * While TMUX runs on all of them, they have built-in multiplexing, so you terminal sessions without requiring TMUX.

      * Super configurable and in some cases programable

      * Excellent typeface support, including ligatures, which I liker

      * A quality of life issue: you don't have to copy and paste URLs; you just right-click them in the terminal.

      * Excellent typeface support

    • corytheboyd 19 hours ago

      I just recently decided to replace iterm2 with wezterm when I started moving macbook over to nix. iterm2 is about the only one that didn’t work well for this, since you can’t source control the configuration (import/export doesn’t cut it)

      Any of the ones you mentioned would probably work good with nix too. I don’t really care about the config being scriptable at all, it was just the first terminal that easily let me set all of the keyboard shortcuts I wanted, so I stuck with it.

      • jamesgeck0 19 hours ago

        iTerm2 does support source control; I've got my settings in a git repo managed by Chezmoi. In the settings dialog, under "General" -> "Settings", there's an "External settings: Load settings from a custom folder or URL" option.

        • pksebben 18 hours ago

          I've also gone wez from iterm2, and you hit upon why. Don't ever make me click on things. I can't script => modify => export clicking on things. When you make me click on things, you've defined my interface for me, which I did not ask for.

          I suppose I'm a bit of an extremist, though.

          • theshrike79 6 hours ago

            Nah, I want my configurations to be deterministic.

            I put config in dir, launch app. App should look like config.

            If it doesn't it's the app's fault.

            There are a limited number of applications I tolerate this behaviour from, but not many.

            • pksebben an hour ago

              Almost entirely with you on that, actually. But OS and other environment differences frequently demand some sort of tweaking, which I absolutely do not want to do by hand if I've done it before.

    • binary132 15 hours ago

      Low latency full screen editor is really nice if you have a reasonably fast monitor and appreciate or need a terminal based editor.

    • fwip 19 hours ago

      To be completely honest, the reason I switched was for true-color support in my editor (vim), rather than being limited to just 256 colors.

    • foobarqux 19 hours ago

      The main features I use are

      1. quick-select the output in the terminal (select files/paths, urls, etc and either copy or paste them at the cursor). This is very useful as you often don't have the foresight to pipe the command to pipe the output of the command to some selection mechanism and even placing text on the line-editor is not that easy by default.

      2. view images (sixel or kitty protocol). This is pretty useful visual analog to cat that doesn't require opening another program and works over ssh. Also for video.

      There are some other nice utilities for doing things like downloading files directly in the terminal (it2dl for iterm and kitten transfer for kitty).

      kitty doesn't work out of the box on macos if I remember; you have to set configuration for option/command etc.

    • bsder 13 hours ago

      > Could someone sell me on one of these alternative terminals (kitty, ghostty, wez, etc)?

      Because these terminals all use the Kitty protocol, you can finally detect a single ESC press without a timeout hack as well as use shift with arrow keys to do text selection.

      The fact that it has taken until 2025 to be able to do something this basic is pathetic.

  • woile 11 hours ago

    WezTerm on nix here, it just works, it's very fast and combined with spaceship it shows everything I need. And nix makes sure in whichever environment I'm in, it will be installed

  • barrkel 16 hours ago

    I found wezterm pane resizing to be very glitchy, and using native panes along with the muxing server was about 80% of the reason I wanted to use it. But for whatever reason, maybe font related, the resizing logic is unstable and it gets into weird states, glitching and flickering etc. Nightly vs stable made bo difference.

  • levkk 18 hours ago

    The only thing I want from WezTerm is a warning when I'm about to close a tab. The tabs are too small and the x is easy to hit by accident... thousand lines of bash history and temp env vars gone in an instant.

    Otherwise, it's awesome and my default terminal everywhere.

    • keithnz 18 hours ago

      you can configure that...

      • levkk 18 hours ago

        Please show me where. It only works for tabs that have a running process.

        • keithnz 18 hours ago

          oh, you might be doing it via the UI, I turn off all the UI elements and hotkey everything, if you use hotkeys you can add a thing like :- action = wezterm.action.CloseCurrentTab { confirm = true },

  • submeta 18 hours ago

    WezTerm is an absolute joy to use: Scriptable (in Lua), allows creating your own shortcuts, has a command palette, has something like tmux (called mux) for which I have created lua scripts to setup my workspace for different projects. Something like tmuxinator impelemented in WezTerm. - I still use tmux, but mux is nice as well, and I can use splits and navigation natively in WezTerm, no need for prefix-{command} like in tmux. But can have workspaces in WezTerm.

    It allows adding a custom background image, also transparent background, and I can toggle all of that via my custom shortcuts: Transparent on/off, background image on/off/rotate randomly.

    It is such a joy to use and so beautiful. That plus neovim, yazi file browser, and lazygit: Dreamteam. Best dev environment I ever had.

  • semiinfinitely 19 hours ago

    It is impossible for me to take seriously someone who puts spotify into their command line terminal.