Installation
============

If khal is packaged for your OS/distribution, using your system's
standard package manager is probably the easiest way to install khal.
khal has been packaged for, among others: Arch Linux (stable_ and development_
versions), Debian_, Fedora_, FreeBSD_, Guix_, and pkgsrc_ (or see repology_ for
a more complete list).

.. _stable: https://www.archlinux.org/packages/community/any/khal/
.. _development: https://aur.archlinux.org/packages/khal-git/
.. _Debian: https://packages.debian.org/search?keywords=khal&searchon=names
.. _Fedora: https://admin.fedoraproject.org/pkgdb/package/rpms/khal/
.. _FreeBSD: https://www.freshports.org/deskutils/py-khal/
.. _Guix: http://www.gnu.org/software/guix/packages/
.. _pkgsrc: http://pkgsrc.se/time/khal
.. _repology: https://repology.org/project/python:khal/versions

If a package isn't available (or it is outdated) you need to fall back to one
of the methods mentioned below.

Install via Python's Package Managers
-------------------------------------

Since *khal* is written in python, you can use one of the package managers
available to install python packages, e.g. *pip*.

You can install the latest released version of *khal* by executing::

    pip install khal

or the latest development version by executing::

     pip install git+git://github.com/pimutils/khal.git

This should also take care of installing all required dependencies.  If in
doubt, do not use `sudo pip install` but install `pip install khal --user`.
Especially if using the `--user` flag, *khal* might be installed to
`~/.local/bin`.  So if your shell cannot find *khal*, you might want to check
there and add that `folder to your $PATH
<https://askubuntu.com/questions/60218/how-to-add-a-directory-to-the-path>`_.

Otherwise, you can always download the latest release from pypi_ and execute::

        python setup.py install

or better::

        pip install .

in the unpacked distribution folder.

Since version 0.12.0, *khal* **only supports python 3.9+**. If you have
python 2 and 3 installed in parallel you might need to use `pip3` instead of
`pip` and `python3` instead of `python`. In case your operating system cannot
deal with python 2 and 3 packages concurrently, we suggest installing *khal* in
a virtualenv_ (e.g. by using virtualenvwrapper_ or with the help of pipsi_) and
then starting khal from that virtual environment.

.. _pipsi: https://github.com/mitsuhiko/pipsi
.. _pypi: https://pypi.python.org/pypi/khal
.. _virtualenv: https://virtualenv.pypa.io
.. _virtualenvwrapper: http://virtualenvwrapper.readthedocs.org/

Shell Completion
----------------
khal uses click_ for it's commpand line interface. click can automatically
generate completion_ files for bash, fish, and zsh which can either be generated
and sourced each time your shell is started or, generated once, save to a file
and sourced from there. The latter version is much more efficient.

.. note::
    If you package khal, please generate and include the completion file in the
    package if possible.

.. _click: https://click.palletsprojects.com
.. _completion: https://click.palletsprojects.com/en/8.1.x/shell-completion/

bash
~~~~
For bash, you can either add the following line to your ``.bashrc``::

    eval "$(_KHAL_COMPLETE=bash_source khal)"

Or, save the file somewhere::

    _KHAL_COMPLETE=bash_source khal > ~/.khal-complete.bash

and then source it from your ``.bashrc``::

    . ~/.khal-complete.bash

zsh
~~~
For zsh, you can either add the following line to your ``.zshrc``::

   eval "$(_KHAL_COMPLETE=zsh_source khal)"

Or, save the file somewhere::

   _KHAL_COMPLETE=zsh_source khal > ~/.khal-complete.zsh

and then source it from your ``.zshrc``::

   . ~/.khal-complete.zsh

fish
~~~~
For fish, add this to ``~/.config/fish/completions/khal.fish``::

   eval (env _KHAL_COMPLETE=fish_source khal)

Or save the script to ``~/.config/fish/completions/khal.fish``::

   _KHAL_COMPLETE=fish_source khal > ~/.config/fish/completions/khal.fish

Note, that the latter basically does the same as the former and no efficiency is
gained.

.. _requirements:

Requirements
------------

*khal* is written in python and can run on Python 3.9+. It requires a Python
with ``sqlite3`` support enabled (which is usually the case).

If you are installing python via *pip* or from source, be aware that since
*khal* indirectly depends on lxml_ you need to either install it via your
system's package manager or have python's libxml2's and libxslt1's headers
(included in a separate "development package" on some distributions) installed.

.. _icalendar: https://github.com/collective/icalendar
.. _vdirsyncer: https://github.com/pimutils/vdirsyncer
.. _lxml: http://lxml.de/

Packaging
---------

If your packages are generated by running ``setup.py install`` or some similar
mechanism, you'll end up with very slow entry points (eg: ``/usr/bin/khal``).
Package managers should use the files included in ``bin`` as a replacement for
those.

The root cause of the issue is really how python's setuptools generates these
and outside of the scope of this project

If your packages are generated using python wheels, this should not be an issue
(much like it won't be an issue for users installing via ``pip``).
