Tutorial – Writing your first gRPC service in Python

In my last blog post(here) I explained the advantages of moving your micro services to gRPC, and I felt that a tutorial for writing a service in gRPC was due for the same. This tutorial is going to be in Python(since it’s the most easiest to follow), however gRPC is language independent.

We’re going to write a simple service, which returns the Hex digest of any text you send it.

For this tutorial I am going to use python 3.6(and this is only for Mac and Linux, but I am sure the only thing different for windows will be the setup process)

Setup and install virtual env with python3 on your system. This is a great article for setting it up if you’re are doing it for the first time.

Starting with grpcio

Assuming you have successfully installed virtual env on your system along with python, you can start by running the following commands:

Next you need to install grpcio in your virtual environment to start working with it:

At this point your virtual environment has all the relevant libraries to starting your grpc service.

A gRPC service has 3 parts to it:

  1. Proto File: Contains all the service definitions for the current package. This will be used for generating stubs to be used by the gRPC server and client.
  2. gRPC Server: This is used for servicing incoming requests (kinda like an HTTP server)
  3. gRPC Client: This is distributed out to other people so that they can access our server using it. Essentially this makes the gRPC call as simple as calling a native function in the same code base itself.

Writing the Proto File

Let start by writing the proto file for the service. Create a file called digestor.proto and copy the text below(explanation follows):

The first line specifies the type/dialect of the proto definition:

The next couple of lines are commented out. They are package definitions for Java(Please don’t ever expect me to write a tutorial for that ;-P ) incase we needed stubs to be generated for java as well(since gRPC offers polyglot implementations).

The last line declares the name of the gRPC package.

The block of config declares the gRPC services. This essentially states that there’s a collection of services/service called Digestor, which currently has a single service called GetDigest. This takes as Input a message type DigestMessage and return a message type DigestedMessage. Definitions for both these message types is declared below the service declaration. 


Generating the Stubs

Run the following command to generate the gRPC stubs from the proto file:

You should be to see 2 files called digestor_pb2.py and digestor_pb2_grpc.py generated. These are the two stub files using which we can write out gRPC server and gRPC client.

Writing the gRPC Server

We can now start writing the gRPC server. Create a file called digester_server.py and save the code below in it. Follow the comments in the code for the explanations.

Run the above python file to start a gRPC server.

Writing the gRPC Client

The final step in writing our little gRPC service is to write a client which we will use to access to the rpc running on the server. Save the below file as digestor_client.py


This completes our Simple gRPC service.

Testing it

With the server running in another console(but in the same virtualenv), fire up the python interpreter, and write the following:

Using the above client instance you can call the gRPC without doing any sort of network handling. Just call the get_digest function on the client object to invoke the gRPC. For example:

prints out the output


Where Now?

This is just the beginning. You can implement whatever type of services you want on top of this. A topic to explore further would be streaming in gRPC(check it out here).

You can find all the code for this example here.

Using gRPC in production? Tell me all about it!!!


  1. currs.get_digest(‘Random12312312ascsadvsascdaasdcsadcsds’)
    I think “currs” should be replaced with “curr_client”

  2. This is very simple and straight forward introduction to gRPC development . Much appreciated .

  3. Thats great, thank you so much.

    There is a small type you might wanna fix in the testing.

    Instead of

Leave a Reply