1Installation
2============
3
4If khal is packaged for your OS/distribution, using your system's
5standard package manager is probably the easiest way to install khal.
6khal has been packaged for, among others: Arch Linux (stable_ and development_
7versions), Debian_, Fedora_, FreeBSD_, Guix_, and pkgsrc_.
8
9.. _stable: https://www.archlinux.org/packages/community/any/khal/
10.. _development: https://aur.archlinux.org/packages/khal-git/
11.. _Debian: https://packages.debian.org/search?keywords=khal&searchon=names
12.. _Fedora: https://admin.fedoraproject.org/pkgdb/package/rpms/khal/
13.. _FreeBSD: https://www.freshports.org/deskutils/py-khal/
14.. _Guix: http://www.gnu.org/software/guix/packages/
15.. _pkgsrc: http://pkgsrc.se/time/khal
16
17If a package isn't available (or it is outdated) you need to fall back to one
18of the methods mentioned below.
19
20Install via Python's Package Managers
21-------------------------------------
22
23Since *khal* is written in python, you can use one of the package managers
24available to install python packages, e.g. *pip*.
25
26You can install the latest released version of *khal* by executing::
27
28    pip install khal
29
30or the latest development version by executing::
31
32     pip install git+git://github.com/pimutils/khal.git
33
34This should also take care of installing all required dependencies.  If in
35doubt, do not use `sudo pip install` but install `pip install khal --user`.
36Especially if using the `--user` flag, *khal* might be installed to
37`~/.local/bin`.  So if your shell cannot find *khal*, you might want to check
38there and add that `folder to your $PATH
39<https://askubuntu.com/questions/60218/how-to-add-a-directory-to-the-path>`_.
40
41Otherwise, you can always download the latest release from pypi_ and execute::
42
43        python setup.py install
44
45or better::
46
47        pip install .
48
49in the unpacked distribution folder.
50
51Since version 0.10, *khal* **only supports python 3.6+**. If you have
52python 2 and 3 installed in parallel you might need to use `pip3` instead of
53`pip` and `python3` instead of `python`. In case your operating system cannot
54deal with python 2 and 3 packages concurrently, we suggest installing *khal* in
55a virtualenv_ (e.g. by using virtualenvwrapper_ or with the help of pipsi_) and
56then starting khal from that virtual environment.
57
58.. _pipsi: https://github.com/mitsuhiko/pipsi
59.. _pypi: https://pypi.python.org/pypi/khal
60.. _virtualenv: https://virtualenv.pypa.io
61.. _virtualenvwrapper: http://virtualenvwrapper.readthedocs.org/
62
63.. _requirements:
64
65Requirements
66------------
67
68*khal* is written in python and can run on Python 3.5+. It requires a Python
69with ``sqlite3`` support enabled (which is usually the case).
70
71If you are installing python via *pip* or from source, be aware that since
72*khal* indirectly depends on lxml_ you need to either install it via your
73system's package manager or have python's libxml2's and libxslt1's headers
74(included in a separate "development package" on some distributions) installed.
75
76.. _icalendar: https://github.com/collective/icalendar
77.. _vdirsyncer: https://github.com/pimutils/vdirsyncer
78.. _lxml: http://lxml.de/
79
80Packaging
81---------
82
83If your packages are generated by running ``setup.py install`` or some similar
84mechanism, you'll end up with very slow entry points (eg: ``/usr/bin/khal``).
85Package managers should use the files included in ``bin`` as a replacement for
86those.
87
88The root cause of the issue is really how python's setuptools generates these
89and outside of the scope of this project
90
91If your packages are generated using python wheels, this should not be an issue
92(much like it won't be an issue for users installing via ``pip``).
93