Build from source#
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.
kitty is designed to run from source, for easy hack-ability. All you need to get started is a C compiler and the go compiler. After installing those, run the following commands:
git clone https://github.com/kovidgoyal/kitty.git && cd kitty
That’s it, kitty will be built from source, magically. You can run it as
This works, because the
./dev.sh build command downloads all the major
dependencies of kitty as pre-built binaries for your platform and builds kitty
to use these rather than system libraries.
If you make changes to kitty code, simply re-run
to build kitty with your changes.
If you plan to run kitty from source long-term, there are a couple of
caveats to be aware of. You should occasionally run
to have the dependencies re-downloaded as they are updated periodically.
Also, the built kitty executable assumes it will find source in whatever
directory you first ran
./dev.sh build in. If you move/rename the
make clean && ./dev.sh build. You should also create
symlinks to the
kitten binaries from somewhere
in your PATH so that they can be conveniently launched.
On macOS, you can use
kitty/launcher/kitty.app to run kitty as well,
but note that this is an unsigned kitty.app so some functionality such as
notifications will not work as Apple disallows this. If you need this
functionality, you can try signing the built
kitty.app with a self
signed certificate, see for example, here.
Building in debug mode#
The following will build with debug symbols:
./dev.sh build --debug
To build with sanitizers and debug symbols:
./dev.sh build --debug --sanitize
For more help on the various options supported by the build script:
./dev.sh build -h
Building the documentation#
To have the kitty documentation available locally, run:
./dev.sh deps -for-docs && ./dev.sh docs
To develop the docs, with live reloading, use:
./dev.sh deps -for-docs && ./dev.sh docs -live-reload
These dependencies are needed when building against system libraries only.
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)
go>= 1.21 (see
go.modfor go packages used during building)
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:
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
nix-shell will automatically fetch all required dependencies and
make them available in the newly spawned shell.
Then proceed with
make app according to the platform specific
Notes for Linux/macOS packagers#
While kitty does use Python, it is not a traditional Python package, so please do not install it in site-packages. Instead run:
This will install kitty into the directory
linux-package. You can run
linux-package/bin/kitty. All the files needed to run kitty
will be in
linux-package/lib/kitty. The terminfo file will be installed
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
You should probably split kitty into three packages:
Installs the terminfo file
Installs the shell integration scripts (the contents of the shell-integration directory in the kitty source code), probably to
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.
You need a couple of extra dependencies to build linux-package.
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.
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:
Then setup the cross compile environment (CC, CFLAGS, PATH, etc.) and run:
This will create the cross compiled build in the