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
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.
Dependencies#
Run-time dependencies:
python
>= 3.8harfbuzz
>= 2.2.0zlib
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
orclang
go
>= 1.20 (seego.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
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
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.