Build from source#
kitty is designed to run from source, for easy hack-ability. Make sure the following dependencies are installed first.
If you just want to test the latest changes to kitty you dont need to build from source. Instead install the latest nightly build.
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 enviroment 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.
freetype(not needed on macOS)
fontconfig(not needed on macOS)
libcanberra(not needed on macOS)
ImageMagick(optional, needed to use the
kitty +kitten icattool to display images in the terminal)
pygments(optional, needed for syntax highlighting in
kitty +kitten diff)
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:
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:
You can run kitty, as:
If that works, you can create a symlink to the launcher in
some other directory on your PATH so that you can run kitty using
Building kitty.app on macOS from source#
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.
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.
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.
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
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 instructions above.
A basic debug build can be done with:
This includes debug info in the binary for better traces. To build with address sanitizer, use:
Which will result in a debug binary that uses the address sanitizer as well.
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:
python3 setup.py linux-package
This will install kitty into the directory
linux-package. You can run kitty
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
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.
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
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.