1Caveats
2=======
3
4.. contents::
5   :local:
6
7.. _python_caveat:
8
9Python
10------
11
12LLDB has a powerful scripting interface which is accessible through Python.
13Python is available either from within LLDB through a (interactive) script
14interpreter, or as a Python module which you can import from the Python
15interpreter.
16
17To make this possible, LLDB links against the Python shared library. Linking
18against Python comes with some constraints to be aware of.
19
201.  It is not possible to build and link LLDB against a Python 3 library and
21    use it from Python 2 and vice versa.
22
232.  It is not possible to build and link LLDB against one distribution on
24    Python and use it through a interpreter coming from another distribution.
25    For example, on macOS, if you build and link against Python from
26    python.org, you cannot import the lldb module from the Python interpreter
27    installed with Homebrew.
28
293.  To use third party Python packages from inside LLDB, you need to install
30    them using a utility (such as ``pip``) from the same Python distribution as
31    the one used to build and link LLDB.
32
33The previous considerations are especially important during development, but
34apply to binary distributions of LLDB as well.
35
36LLDB in Xcode on macOS
37``````````````````````
38
39Users of lldb in Xcode on macOS commonly run into these issues when they
40install Python, often unknowingly as a dependency pulled in by Homebrew or
41other package managers. The problem is the symlinks that get created in
42``/usr/local/bin``, which comes before ``/usr/bin`` in your path. You can use
43``which python3`` to check to what it resolves.
44
45To be sure you use the Python that matches with the lldb in Xcode use ``xcrun``
46or use the absolute path to the shims in ``/usr/bin``.
47
48::
49
50   $ xcrun python3
51   $ /usr/bin/python3
52
53Similarly, to install packages and be able to use them from within lldb, you'll
54need to install them with the matching ``pip3``.
55
56::
57
58   $ xcrun pip3
59   $ /usr/bin/pip3
60
61The same is true for Python 2. Although Python 2 comes with the operating
62system rather than Xcode, you can still use ``xcrun`` to launch the system
63variant.
64
65::
66
67   $ xcrun python
68   $ /usr/bin/python
69
70Keep in mind that Python 2 is deprecated and no longer maintained. Future
71versions of macOS will not include Python 2.7.
72