Build from source - kitty
Description: Build status kitty is designed to run from source, for easy hack-ability. Make sure the following dependencies are installed first. Dependencies: Run-time dependencies: python>= 3.8, harfbuzz>= 2.2...

Hide navigation sidebar
Hide table of contents sidebar
Back to top
Toggle table of contents sidebar

# Build from source

kitty is designed to run from source, for easy hack-ability. Make sure the following dependencies are installed first.

Note

If you just want to test the latest changes to kitty, you don’t need to build from source. Instead install the latest nightly build.

Note

If you are making small changes only to the Python parts of kitty, there is no need to build kitty at all, instead, assuming you have installed the official kitty binaries, you can simply set the `KITTY_DEVELOP_FROM` environment variable to point to the directory into which you have checked out the kitty source code. kitty will then load its Python code from there. You should use a version of the source that matches the binary version as closely as possible, since the two are tightly coupled.

## Dependencies

Run-time dependencies:

- `python` >= 3.8

- `harfbuzz` >= 2.2.0

- `zlib`

- `libpng`

- `liblcms2`

- `librsync`

- `openssl`

- `freetype` (not needed on macOS)

- `fontconfig` (not needed on macOS)

- `libcanberra` (not needed on macOS)

- `ImageMagick` (optional, needed to display uncommon image formats in the terminal)

Build-time dependencies:

- `gcc` or `clang`

- `go` >= 1.20 (see `go.mod` for go packages used during building)

- `pkg-config`

- For building on Linux in addition to the above dependencies you might also need to install the following packages, if they are not already installed by your distro:

  - `libdbus-1-dev`

  - `libxcursor-dev`

  - `libxrandr-dev`

  - `libxi-dev`

  - `libxinerama-dev`

  - `libgl1-mesa-dev`

  - `libxkbcommon-x11-dev`

  - `libfontconfig-dev`

  - `libx11-xcb-dev`

  - `liblcms2-dev`

  - `libssl-dev`

  - `libpython3-dev`

  - `librsync-dev`

## Install and run from source

    git clone https://github.com/kovidgoyal/kitty && cd kitty

Now build the native code parts of kitty with the following command:

    make

You can run kitty, as:

    ./kitty/launcher/kitty

If that works, you can create a symlink to the launcher in `~/bin` or some other directory on your PATH so that you can run kitty using just `kitty`.

To have the kitty documentation available locally, run:

    python3 -m pip install -r docs/requirements.txt && make docs

To develop the docs, with live reloading, use:

    python3 -m pip install -r docs/requirements.txt && make develop-docs

## Building kitty.app on macOS from source

Run:

    python3 -m pip install -r docs/requirements.txt && make docs
    make app

Building the docs needs to be done only once.

This `kitty.app` unlike the released one does not include its own copy of Python and the other dependencies. So if you ever un-install/upgrade those dependencies you might have to rebuild the app.

Note

The released `kitty.dmg` includes all dependencies, unlike the `kitty.app` built above and is built automatically by using the bypy framework however, that is designed to run on Linux and is not for the faint of heart.

Note

Apple disallows certain functionality, such as notifications for unsigned applications. If you need this functionality, you can try signing the built `kitty.app` with a self signed certificate, see for example, here.

Note

If you are facing issues with `linker` while building, try with a `brew` installed Python instead, see #289 for more discussion.

## Build and run from source with Nix

On NixOS or any other Linux or macOS system with the Nix package manager installed, execute nix-shell to create the correct environment to build kitty or use `nix-shell --pure` instead to eliminate most of the influence of the outside system, e.g. globally installed packages. `nix-shell` will automatically fetch all required dependencies and make them available in the newly spawned shell.

Then proceed with `make` or `make app` according to the platform specific instructions above.

## Debug builds

A basic debug build can be done with:

    make debug

This includes debug info in the binary for better traces. To build with address sanitizer, use:

    make asan

Which will result in a debug binary that uses the address sanitizer as well.

## Notes for Linux/macOS packagers

The released kitty source code is available as a tarball from the GitHub releases page.

While kitty does use Python, it is not a traditional Python package, so please do not install it in site-packages. Instead run:

    make linux-package

This will install kitty into the directory `linux-package`. You can run kitty with `linux-package/bin/kitty`. All the files needed to run kitty will be in `linux-package/lib/kitty`. The terminfo file will be installed into `linux-package/share/terminfo`. Simply copy these files into `/usr` to install kitty. In other words, `linux-package` is the staging area into which kitty is installed. You can choose a different staging area, by passing the `--prefix` argument to `setup.py`.

You should probably split kitty into three packages:

`kitty-terminfo`

  Installs the terminfo file

`kitty-shell-integration`

  Installs the shell integration scripts (the contents of the shell-integration directory in the kitty source code), probably to `/usr/share/kitty/shell-integration`

`kitty`

  Installs the main program

This allows users to install the terminfo and shell integration files on servers into which they ssh, without needing to install all of kitty. The shell integration files must still be present in `lib/kitty/shell-integration` when installing the kitty main package as the kitty program expects to find them there.

Note

You need a couple of extra dependencies to build linux-package. `tic` to compile terminfo files, usually found in the development package of `ncurses`. Also, if you are building from a git checkout instead of the released source code tarball, you will need to install the dependencies from `docs/requirements.txt` to build the kitty documentation. They can be installed most easily with `python -m pip -r docs/requirements.txt`.

This applies to creating packages for kitty for macOS package managers such as Homebrew or MacPorts as well.

## Cross compilation

While cross compilation is neither officially supported, nor recommended, as it means the test suite cannot be run for the cross compiled build, there is some support for cross compilation. Basically, run:

    make prepare-for-cross-compile

Then setup the cross compile environment (CC, CFLAGS, PATH, etc.) and run:

    make cross-compile

This will create the cross compiled build in the `linux-package` directory.