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