src/python/grpcio/README.rst

   1 gRPC Python
   2 ===========
   3
   4 |compat_check_pypi|
   5
   6 Package for gRPC Python.
   7
   8 .. |compat_check_pypi| image:: https://python-compatibility-tools.appspot.com/one_badge_image?package=grpcio
   9    :target: https://python-compatibility-tools.appspot.com/one_badge_target?package=grpcio
  10
  11 Supported Python Versions
  12 -------------------------
  13 Python >= 3.5
  14
  15 Deprecated Python Versions
  16 --------------------------
  17 Python == 2.7. Python 2.7 support will be removed on January 1, 2020.
  18
  19 Installation
  20 ------------
  21
  22 gRPC Python is available for Linux, macOS, and Windows.
  23
  24 Installing From PyPI
  25 ~~~~~~~~~~~~~~~~~~~~
  26
  27 If you are installing locally...
  28
  29 ::
  30
  31   $ pip install grpcio
  32
  33 Else system wide (on Ubuntu)...
  34
  35 ::
  36
  37   $ sudo pip install grpcio
  38
  39 If you're on Windows make sure that you installed the :code:`pip.exe` component
  40 when you installed Python (if not go back and install it!) then invoke:
  41
  42 ::
  43
  44   $ pip.exe install grpcio
  45
  46 Windows users may need to invoke :code:`pip.exe` from a command line ran as
  47 administrator.
  48
  49 n.b. On Windows and on Mac OS X one *must* have a recent release of :code:`pip`
  50 to retrieve the proper wheel from PyPI. Be sure to upgrade to the latest
  51 version!
  52
  53 Installing From Source
  54 ~~~~~~~~~~~~~~~~~~~~~~
  55
  56 Building from source requires that you have the Python headers (usually a
  57 package named :code:`python-dev`).
  58
  59 ::
  60
  61   $ export REPO_ROOT=grpc  # REPO_ROOT can be any directory of your choice
  62   $ git clone -b $(curl -L https://grpc.io/release) https://github.com/grpc/grpc $REPO_ROOT
  63   $ cd $REPO_ROOT
  64   $ git submodule update --init
  65
  66   # For the next two commands do `sudo pip install` if you get permission-denied errors
  67   $ pip install -rrequirements.txt
  68   $ GRPC_PYTHON_BUILD_WITH_CYTHON=1 pip install .
  69
  70 You cannot currently install Python from source on Windows. Things might work
  71 out for you in MSYS2 (follow the Linux instructions), but it isn't officially
  72 supported at the moment.
  73
  74 Troubleshooting
  75 ~~~~~~~~~~~~~~~
  76
  77 Help, I ...
  78
  79 * **... see a** :code:`pkg_resources.VersionConflict` **when I try to install
  80   grpc**
  81
  82   This is likely because :code:`pip` doesn't own the offending dependency,
  83   which in turn is likely because your operating system's package manager owns
  84   it. You'll need to force the installation of the dependency:
  85
  86   :code:`pip install --ignore-installed $OFFENDING_DEPENDENCY`
  87
  88   For example, if you get an error like the following:
  89
  90   ::
  91
  92     Traceback (most recent call last):
  93     File "<string>", line 17, in <module>
  94      ...
  95     File "/usr/lib/python2.7/dist-packages/pkg_resources.py", line 509, in find
  96       raise VersionConflict(dist, req)
  97     pkg_resources.VersionConflict: (six 1.8.0 (/usr/lib/python2.7/dist-packages), Requirement.parse('six>=1.10'))
  98
  99   You can fix it by doing:
 100
 101   ::
 102
 103     sudo pip install --ignore-installed six
 104
 105 * **... see the following error on some platforms**
 106
 107   ::
 108
 109     /tmp/pip-build-U8pSsr/cython/Cython/Plex/Scanners.c:4:20: fatal error: Python.h: No such file or directory
 110     #include "Python.h"
 111                     ^
 112     compilation terminated.
 113
 114   You can fix it by installing `python-dev` package. i.e
 115
 116   ::
 117
 118     sudo apt-get install python-dev
 119