> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/wezterm/wezterm/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install WezTerm on Linux, macOS, Windows, or FreeBSD using your preferred package manager or installer

# Installing WezTerm

WezTerm is available pre-built for all major platforms. Choose your operating system below to get started.

<Tabs>
  <Tab title="Linux">
    ## Linux Installation

    WezTerm supports multiple Linux distributions and installation methods. Choose the one that best fits your workflow.

    ### Recommended: Package Managers

    <Accordion title="Flatpak (Universal)">
      Flatpak provides a sandboxed installation that works across all Linux distributions.

      <Warning>
        Flatpaks run in an isolated sandbox which may limit some functionality for power users. Consider using a native package if you need full system integration.
      </Warning>

      <Steps>
        <Step title="Setup Flatpak">
          First, [setup flatpak on your system](https://flatpak.org/setup/) if you haven't already.
        </Step>

        <Step title="Install WezTerm">
          ```bash theme={null}
          flatpak install flathub org.wezfurlong.wezterm
          ```
        </Step>

        <Step title="Run WezTerm">
          ```bash theme={null}
          flatpak run org.wezfurlong.wezterm
          ```

          Optionally, create an alias for convenience:

          ```bash theme={null}
          alias wezterm='flatpak run org.wezfurlong.wezterm'
          ```
        </Step>
      </Steps>

      <Note>
        **Flatpak Limitations:**

        * Process inspection (e.g., determining current directory) may not work
        * First run may block until GUI is launched
        * Only stable releases available (no nightly builds)
      </Note>
    </Accordion>

    <Accordion title="Ubuntu/Debian (APT)">
      Install via the official APT repository for automatic updates.

      <Steps>
        <Step title="Add APT Repository">
          ```bash theme={null}
          curl -fsSL https://apt.fury.io/wez/gpg.key | sudo gpg --yes --dearmor -o /usr/share/keyrings/wezterm-fury.gpg
          echo 'deb [signed-by=/usr/share/keyrings/wezterm-fury.gpg] https://apt.fury.io/wez/ * *' | sudo tee /etc/apt/sources.list.d/wezterm.list
          sudo chmod 644 /usr/share/keyrings/wezterm-fury.gpg
          ```
        </Step>

        <Step title="Update and Install">
          <CodeGroup>
            ```bash Stable theme={null}
            sudo apt update
            sudo apt install wezterm
            ```

            ```bash Nightly theme={null}
            sudo apt update
            sudo apt install wezterm-nightly
            ```
          </CodeGroup>

          <Note>
            The nightly build conflicts with the stable build. You can install one or the other, but not both simultaneously.
          </Note>
        </Step>
      </Steps>
    </Accordion>

    <Accordion title="Fedora/RHEL (Copr)">
      Install nightly builds via Copr for Fedora, RHEL, CentOS Stream, and openSUSE.

      <Tabs>
        <Tab title="Fedora/RHEL/CentOS">
          ```bash theme={null}
          sudo dnf copr enable wezfurlong/wezterm-nightly
          sudo dnf install wezterm
          ```

          To update:

          ```bash theme={null}
          sudo dnf update wezterm
          ```
        </Tab>

        <Tab title="Fedora Atomic (Silverblue/Kinoite)">
          ```bash theme={null}
          sudo wget https://copr.fedorainfracloud.org/coprs/wezfurlong/wezterm-nightly/repo/fedora-$(rpm -E %fedora)/wezfurlong-wezterm-nightly-fedora-$(rpm -E %fedora).repo -O /etc/yum.repos.d/_copr:copr.fedorainfracloud.org:wezfurlong:wezterm-nightly.repo
          sudo rpm-ostree install wezterm
          ```
        </Tab>

        <Tab title="openSUSE">
          ```bash theme={null}
          sudo zypper in dnf
          sudo dnf copr enable wezfurlong/wezterm-nightly opensuse-tumbleweed-x86_64
          sudo dnf install wezterm
          ```

          Replace `opensuse-tumbleweed-x86_64` with your platform:

          * `opensuse-tumbleweed-x86_64` or `opensuse-tumbleweed-aarch64`
          * `opensuse-leap-15.5-x86_64` or `opensuse-leap-15.5-aarch64`
        </Tab>
      </Tabs>

      <Info>
        **Supported Distributions:**

        * Fedora 38, 39, 40, rawhide
        * CentOS Stream 8, 9
        * RHEL 8, 9
        * openSUSE Leap 15.5, Tumbleweed
        * Available for x86\_64 and aarch64
      </Info>
    </Accordion>

    <Accordion title="Arch Linux">
      WezTerm is available in the official Extra repository.

      ```bash theme={null}
      sudo pacman -S wezterm ttf-nerd-fonts-symbols-mono
      ```

      <Tip>
        Be sure to install `ttf-nerd-fonts-symbols-mono` for proper symbol rendering!
      </Tip>

      For the latest development version, use the AUR:

      ```bash theme={null}
      # Using yay
      yay -S wezterm-git
      ```
    </Accordion>

    <Accordion title="NixOS/Nix">
      WezTerm is available in nixpkgs.

      <Tabs>
        <Tab title="NixOS Configuration">
          ```nix theme={null}
          # configuration.nix
          {
            environment.systemPackages = [
              pkgs.wezterm
            ];
          }
          ```
        </Tab>

        <Tab title="Flake (Latest)">
          For newer versions, use the flake:

          ```nix theme={null}
          # flake.nix
          {
            inputs.wezterm.url = "github:wezterm/wezterm?dir=nix";

            outputs = inputs @ {nixpkgs, ...}: {
              nixosConfigurations.HOSTNAME = nixpkgs.lib.nixosSystem {
                specialArgs = { inherit inputs; };
                modules = [ /* ... */ ];
              };
            };
          }
          ```

          Enable the cachix binary cache to avoid building from source:

          ```nix theme={null}
          # nixosConfiguration module
          {
            nix.settings = {
              substituters = ["https://wezterm.cachix.org"];
              trusted-public-keys = ["wezterm.cachix.org-1:kAbhjYUC9qvblTE+s7S+kl5XM1zVa4skO+E/1IDWdH0="];
            };
          }
          ```
        </Tab>

        <Tab title="home-manager">
          ```nix theme={null}
          # home.nix
          {inputs, pkgs, ...}: {
            programs.wezterm = {
              enable = true;
              package = inputs.wezterm.packages.${pkgs.system}.default;
            };
          }
          ```
        </Tab>
      </Tabs>

      <Warning>
        Git must be available in `$PATH` during evaluation phase when using the wezterm flake, as it uses `builtins.fetchGit`.
      </Warning>
    </Accordion>

    <Accordion title="Linuxbrew">
      For Linuxbrew users:

      <CodeGroup>
        ```bash Stable theme={null}
        brew tap wezterm/wezterm-linuxbrew
        brew install wezterm
        ```

        ```bash Nightly theme={null}
        brew install --HEAD wezterm
        ```
      </CodeGroup>

      To upgrade nightly builds:

      ```bash theme={null}
      brew rm wezterm
      brew install --HEAD wezterm
      ```
    </Accordion>

    ### Standalone Packages

    <Accordion title="AppImage (Portable)">
      AppImage provides a self-contained executable that works across distributions.

      ```bash theme={null}
      # Download stable release
      curl -LO https://github.com/wez/wezterm/releases/download/latest/WezTerm-latest-Ubuntu20.04.AppImage
      chmod +x WezTerm-latest-Ubuntu20.04.AppImage

      # Run directly
      ./WezTerm-latest-Ubuntu20.04.AppImage

      # Or move to your bin directory
      mkdir -p ~/bin
      mv ./WezTerm-latest-Ubuntu20.04.AppImage ~/bin/wezterm
      ~/bin/wezterm
      ```

      <Tip>
        AppImages are perfect for portable installations or trying WezTerm without installing system packages.
      </Tip>
    </Accordion>

    <Accordion title="DEB Packages (Ubuntu/Debian)">
      Download pre-built `.deb` packages for specific Ubuntu/Debian versions:

      ```bash theme={null}
      # Ubuntu 22.04 example
      curl -LO https://github.com/wez/wezterm/releases/download/latest/wezterm-latest.Ubuntu22.04.deb
      sudo apt install -y ./wezterm-latest.Ubuntu22.04.deb
      ```

      **Available distributions:** Ubuntu 20, 22, 24 | Debian 11, 12 (amd64 and arm64)
    </Accordion>

    <Accordion title="RPM Packages (Fedora/CentOS)">
      Download pre-built `.rpm` packages:

      ```bash theme={null}
      # Fedora 39 example
      sudo dnf install -y https://github.com/wez/wezterm/releases/download/latest/wezterm-latest.Fedora39.rpm
      ```

      **Available distributions:** CentOS 9 | Fedora 37, 38, 39, 40
    </Accordion>

    <Info>
      After installation, WezTerm is available as `/usr/bin/wezterm`. Configuration instructions are in the [quick start guide](/quickstart).
    </Info>
  </Tab>

  <Tab title="macOS">
    ## macOS Installation

    WezTerm requires **macOS Mojave (10.14) or later** and is available as a Universal binary supporting both Apple Silicon and Intel processors.

    ### Direct Download (Recommended)

    <Steps>
      <Step title="Download WezTerm">
        Download the latest release:

        * [Stable Release](https://github.com/wez/wezterm/releases/latest/download/WezTerm-macos.zip)
        * [Nightly Build](https://github.com/wez/wezterm/releases/download/nightly/WezTerm-macos.zip)
      </Step>

      <Step title="Install the App">
        1. Extract the ZIP file
        2. Drag `WezTerm.app` to your `Applications` folder
        3. Right-click and select "Open" on first launch (security requirement)
      </Step>

      <Step title="Add CLI to PATH (Optional)">
        To use `wezterm` commands from the terminal, add to your shell profile:

        <CodeGroup>
          ```bash ~/.zshrc theme={null}
          PATH="$PATH:/Applications/WezTerm.app/Contents/MacOS"
          export PATH
          ```

          ```bash ~/.bash_profile theme={null}
          PATH="$PATH:/Applications/WezTerm.app/Contents/MacOS"
          export PATH
          ```
        </CodeGroup>
      </Step>
    </Steps>

    ### Homebrew

    <CodeGroup>
      ```bash Stable theme={null}
      brew install --cask wezterm
      ```

      ```bash Nightly theme={null}
      brew install --cask wezterm@nightly
      ```
    </CodeGroup>

    To upgrade nightly builds:

    ```bash theme={null}
    brew upgrade --cask wezterm@nightly --no-quarantine --greedy-latest
    ```

    <Note>
      The `--greedy-latest` flag forces installation of the absolute latest version, even if an older version satisfies requirements.
    </Note>

    ### MacPorts

    ```bash theme={null}
    sudo port selfupdate
    sudo port install wezterm
    ```

    <Info>
      **Universal Binary Support:**
      All installation methods provide a Universal binary that runs natively on both Apple Silicon (M1/M2/M3) and Intel Macs.
    </Info>
  </Tab>

  <Tab title="Windows">
    ## Windows Installation

    WezTerm requires **Windows 10.0.17763 (October 2018 Update) or later** for Pseudo Console (ConPTY) support.

    ### Setup Installer (Recommended)

    The setup.exe installer provides the easiest installation experience:

    <Steps>
      <Step title="Download Installer">
        * [Stable Release (setup.exe)](https://github.com/wez/wezterm/releases/latest/download/WezTerm-windows-setup.exe)
        * [Nightly Build (setup.exe)](https://github.com/wez/wezterm/releases/download/nightly/WezTerm-windows-setup.exe)
      </Step>

      <Step title="Run Installer">
        1. Run the downloaded `.exe` file
        2. Follow the installation wizard (requires admin privileges)
        3. WezTerm will be installed to Program Files and added to your PATH
      </Step>

      <Step title="Launch WezTerm">
        * Use the Start Menu shortcut
        * Or run `wezterm` from any command prompt
      </Step>
    </Steps>

    <Tip>
      The installer can be scripted using [standard Inno Setup command line options](https://jrsoftware.org/ishelp/index.php?topic=setupcmdline) for automated deployments.
    </Tip>

    ### Package Managers

    <Accordion title="winget (Windows Package Manager)">
      winget is included with the [App Installer](https://www.microsoft.com/en-us/p/app-installer/9nblggh4nns1) from the Microsoft Store.

      <CodeGroup>
        ```powershell Install theme={null}
        winget install wez.wezterm
        ```

        ```powershell Upgrade theme={null}
        winget upgrade wez.wezterm
        ```
      </CodeGroup>
    </Accordion>

    <Accordion title="Scoop">
      WezTerm is available in the "Extras" bucket:

      ```powershell theme={null}
      scoop bucket add extras
      scoop install wezterm
      ```
    </Accordion>

    <Accordion title="Chocolatey">
      Install from the Chocolatey Community Repository:

      ```powershell theme={null}
      choco install wezterm -y
      ```
    </Accordion>

    ### Portable ZIP

    For a portable installation that doesn't require admin privileges:

    <Steps>
      <Step title="Download ZIP">
        * [Stable Release (zip)](https://github.com/wez/wezterm/releases/latest/download/WezTerm-windows-portable.zip)
        * [Nightly Build (zip)](https://github.com/wez/wezterm/releases/download/nightly/WezTerm-windows-portable.zip)
      </Step>

      <Step title="Extract and Run">
        1. Extract the ZIP to any location (e.g., flash drive, user folder)
        2. Double-click `wezterm.exe` to launch
        3. No installation or admin rights required
      </Step>
    </Steps>

    <Info>
      The portable ZIP is perfect for:

      * Running WezTerm from a USB drive
      * Testing without installation
      * Environments where you can't install software
    </Info>
  </Tab>

  <Tab title="FreeBSD">
    ## FreeBSD Installation

    WezTerm is available via the FreeBSD ports system:

    ```bash theme={null}
    pkg install wezterm
    ```

    <Note>
      The version in ports is maintained by the FreeBSD community and may lag behind the latest WezTerm release.
    </Note>

    ### Building from Source

    For the latest version, you can build from source. See the [source build documentation](https://github.com/wez/wezterm/blob/main/docs/install/source.md) for detailed instructions.
  </Tab>
</Tabs>

## Verify Installation

After installation, verify WezTerm is working:

```bash theme={null}
# Check version
wezterm --version

# List available fonts
wezterm ls-fonts

# Show default key bindings
wezterm show-keys
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Quick Start Guide" icon="rocket" href="/quickstart">
    Create your first configuration and customize WezTerm
  </Card>

  <Card title="Configuration Files" icon="file-code" href="/config/files">
    Learn about configuration file locations and structure
  </Card>

  <Card title="Key Bindings" icon="keyboard" href="/config/default-keys">
    Explore default keyboard shortcuts
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/troubleshooting">
    Get help if you encounter issues
  </Card>
</CardGroup>

<Info>
  Need help? Visit [GitHub Discussions](https://github.com/wezterm/wezterm/discussions) or join the [Matrix chat](https://app.element.io/#/room/#wezterm:matrix.org).
</Info>