{"id":41,"date":"2026-10-01T10:18:28","date_gmt":"2026-10-01T04:48:28","guid":{"rendered":"https:\/\/truepythoneer.com\/blog\/?p=41"},"modified":"2026-10-01T10:18:29","modified_gmt":"2026-10-01T04:48:29","slug":"amaze-your-friends-painting-images-google-sheets-python","status":"publish","type":"post","link":"https:\/\/truepythoneer.com\/blog\/amaze-your-friends-painting-images-google-sheets-python\/","title":{"rendered":"Amaze Your Friends by Painting Images on Google Sheets Using Python"},"content":{"rendered":"\n

Google Sheets looks like a tool for numbers, but underneath it is a grid of cells, and every cell can be given a color. Three years ago, on 1 October 2023, I stood on the PyCon India 2023 stage in Hyderabad and showed how Python can use that grid as a canvas for painting images on Google Sheets, one cell per pixel. To mark the third anniversary of that talk, this post walks through the idea, the Google Cloud setup and the code, based on my final slides and the real repository.<\/p>\n\n\n\n

Before the talk, I recorded a short video for my PyCon India proposal, with the explanation and a live demo. Watch the proposal video on YouTube<\/a>.<\/p>\n\n\n\n

You can also read the original proposal on the PyCon India 2023 site<\/a>.<\/p>\n\n\n\n

The idea: a spreadsheet is just a grid of pixels<\/h2>\n\n\n\n

A Google Sheet is a grid of cells, and every cell can have a background color. Similarly, an image is a grid of pixels, and every pixel has a color. As a result, if you match one cell to one pixel, the spreadsheet becomes a canvas for painting images on Google Sheets.<\/p>\n\n\n\n

That is the whole talk, and it came from a small experiment. First, in 2020 I wrote a script that turned images into Excel files, using the xlsxwriter and openpyxl libraries. However, my Python history goes back further: in 2008 I wrote a Sudoku solver for Nokia Symbian 60 phones using Mobile Python. Then, for PyCon India 2023, I moved the idea to Google Sheets, where an API can do the painting from anywhere.<\/p>\n\n\n\n

In practice, the problem breaks into three steps:<\/p>\n\n\n\n

    \n
  1. Read the pixel data of an image.<\/li>\n\n\n\n
  2. Set up a Google Spreadsheet as the canvas.<\/li>\n\n\n\n
  3. Fill each cell with the color of its pixel.<\/li>\n<\/ol>\n\n\n\n

    Two terms matter throughout, because the API uses both. A spreadsheet<\/strong> is the whole book, and a sheet<\/strong> is one page (tab) inside it. The script adds a new sheet for every image you paint, so you can keep many pictures in one spreadsheet.<\/p>\n\n\n\n

    Setting up Google Cloud<\/h2>\n\n\n\n

    Painting images on Google Sheets from Python only works if Google trusts your code. So five setup steps get you there, all in the Google Cloud console.<\/p>\n\n\n\n

      \n
    1. Create a Google Cloud project.<\/strong> I named mine ImageToSheet.<\/li>\n\n\n\n
    2. Enable the Google Sheets API.<\/strong> Open APIs & Services, choose Enable APIs and Services, search for Google Sheets API and enable it.<\/li>\n\n\n\n
    3. Create a service account.<\/strong> Google’s credential guide lists three options: API keys (public data), OAuth client ID (user data with consent) and service account (data owned by your app). Therefore, a script that edits its own sheet needs the service account. I called mine pythonsheetclient<\/code>.<\/li>\n\n\n\n
    4. Create a key for the service account.<\/strong> Open the account, go to the Keys tab, then Add Key and choose JSON. Google warns that downloaded keys are a security risk if they leak, so keep the file out of shared folders. Save it as key.json next to the script; the repository’s .gitignore already excludes that name.<\/li>\n\n\n\n
    5. Share the spreadsheet with the service account.<\/strong> The service account has its own email address, ending in iam.gserviceaccount.com<\/code>. Share the sheet with that address as an Editor, just as you would with a colleague.<\/li>\n<\/ol>\n\n\n\n

      After step 5 the script can open the spreadsheet with the key file. As a result, nothing else needs to be public.<\/p>\n\n\n\n

      The Python, file by file<\/h2>\n\n\n\n

      The project for painting images on Google Sheets is three small files, released under the GNU General Public License v3.0:<\/p>\n\n\n\n

      File<\/th>Job<\/th><\/tr><\/thead>
      ImageToGoogleSheet.py<\/code><\/td>The main script: loads the image, adds a sheet, sends the pixels<\/td><\/tr>
      ImageToJSON.py<\/code><\/td>Turns the pixel array into one big updateCells<\/code> request<\/td><\/tr>
      RequestDataClasses.py<\/code><\/td>The dataclasses that describe that request<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

      Get the code:<\/strong> the full project, including the notebook and sample images, is on GitHub: https:\/\/github.com\/truepythoneer\/ImageToGoogleSheet<\/a>.<\/p>\n\n\n\n

      The snippets below come straight from the repository, with only the progress print<\/code> lines trimmed.<\/p>\n\n\n\n

      Before you run it<\/h3>\n\n\n\n
        \n
      1. Create a fresh environment (I used Anaconda and installed the packages from conda-forge), then install the libraries: pip install pillow numpy google-api-python-client google-auth google-auth-httplib2 httplib2 dataclasses-json tqdm colorama<\/code>.<\/li>\n\n\n\n
      2. Save the service account key next to the script as key.json<\/code>. The repository’s .gitignore<\/code> already excludes key.json<\/code> and *.log<\/code>, so the key stays out of Git.<\/li>\n\n\n\n
      3. Set the environment variable SPREADSHEETID<\/code> to your spreadsheet’s ID. It is the part of the URL after \/d\/<\/code>, and the number after gid=<\/code> is the sheetId<\/code> of one tab:<\/li>\n<\/ol>\n\n\n
        https:\/\/docs.google.com\/spreadsheets\/d\/<spreadsheetId<\/span>><\/span>\/edit#gid=<sheetId<\/span>><\/span><\/code><\/span>Code language:<\/span> HTML, XML<\/span> (<\/span>xml<\/span>)<\/span><\/small><\/pre>\n\n\n
        Then run it with the path of any image:<\/p>\n\n\n
        python ImageToGoogleSheet.py images\/monasmall.png<\/code><\/span><\/pre>\n\n\n
        1. The class and its settings<\/h3>\n\n\n\n
        First, everything hangs off one class. SQUAREWIDTH<\/code> is the pixel size given to every column, and the spreadsheet ID and key file are read here.<\/p>\n\n\n
        class ImageToGoogleSheet:\n\n    def __init__(self):\n        self.imagepath = \"\"\n        self.sheetName = \"\"\n        self.sheetID = 0\n        self.SQUAREWIDTH = 21\n        self.SPREADSHEET_ID = os.environ['SPREADSHEETID']\n        self.SERVICE_KEY = 'key.json'<\/code><\/span><\/pre>\n\n\n
        2. Read the pixels with Pillow<\/h3>\n\n\n\n
        Pillow opens JPG, PNG, GIF, TIFF and BMP files alike. However, images come in color modes such as RGB, CMYK and bitmap, but the sheet needs RGB values, so anything else is converted first. getdata()<\/code> returns every pixel, and NumPy turns that into an array that is easy to index.<\/p>\n\n\n
        def __LoadImage(self<\/span>):\n    inputimage = Image.open(self<\/span>.imagepath)\n\n    self<\/span>.width, self<\/span>.height = inputimage.size\n\n    if<\/span> inputimage.mode != \"RGB\"<\/span>:\n        inputimage = inputimage.convert(\"RGB\"<\/span>)\n\n    image_sequence = inputimage.getdata()\n    self<\/span>.image_array = np.array<\/span>(image_sequence)<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
        3. Connect with a service account<\/h3>\n\n\n\n
        The key file and the Sheets scope give you credentials, and build<\/code> returns a client for the v4 REST API. The method that does all the work is spreadsheets.batchUpdate<\/code>. In other words, it takes a list of requests and applies them in one call.<\/p>\n\n\n
        SCOPES = ['https:\/\/www.googleapis.com\/auth\/spreadsheets'<\/span>]\n\ncreds = service_account.Credentials.from_service_account_file(\n            self<\/span>.SERVICE_KEY, scopes=SCOPES)\n\nservice = build('sheets'<\/span>, 'v4'<\/span>, credentials=creds)<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
        The code wraps this in a __SetupProxy<\/code> helper with a UseProxy<\/code> switch, which is False<\/code> by default. It routes traffic through a local proxy at 127.0.0.1:8888<\/code> so you can watch the API calls while debugging. That path turns off certificate checking, so leave it off otherwise.<\/p>\n\n\n\n
        \"Shashi
        Walking through the batchUpdate slide at PyCon India 2023, Hyderabad.<\/figcaption><\/figure>\n\n\n\n
        4. Add a sheet sized to the image<\/h3>\n\n\n\n
        The first request adds a new sheet with one row per pixel of height and one column per pixel of width. The sheet name is the month, weekday and Unix timestamp, so repeat runs never collide.<\/p>\n\n\n
        now = dt.datetime.now()\nself<\/span>.sheetName = f\"{now:%b} {now:%a} {int(now.timestamp())}\"<\/span>\n\nrequests = []\nrequests.append({\n    \"addSheet\"<\/span>: {\n        \"properties\"<\/span>: {\n            \"title\"<\/span>: self<\/span>.sheetName,\n            \"gridProperties\"<\/span>: {\n                \"rowCount\"<\/span>: self<\/span>.height,\n                \"columnCount\"<\/span>: self<\/span>.width\n            }\n        }\n    }\n})\nbody = {'requests'<\/span>: requests}\n\naddsheetresponse = service.spreadsheets().batchUpdate(\n                        spreadsheetId=self<\/span>.SPREADSHEET_ID,\n                        body=body).execute()<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
        The reply contains the new sheet’s ID, which every later request needs:<\/p>\n\n\n
        self<\/span>.sheetID = addsheetresponse['replies'<\/span>][0<\/span>]['addSheet'<\/span>]['properties'<\/span>]['sheetId'<\/span>]<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
        5. Make the cells square<\/h3>\n\n\n\n
        By default a Google Sheets cell is 21 pixels tall and 100 pixels wide, which would stretch the picture. To fix that, a second request sets every column to SQUAREWIDTH<\/code> (21 pixels), which matches the default row height.<\/p>\n\n\n
        requests = []\nrequests.append({\n    'updateDimensionProperties'<\/span>: {\n        'range'<\/span>: {\n            'sheetId'<\/span>: self<\/span>.sheetID,\n            'dimension'<\/span>: \"COLUMNS\"<\/span>,\n            'startIndex'<\/span>: 0<\/span>,\n            'endIndex'<\/span>: self<\/span>.width,\n        },\n        'properties'<\/span>: {'pixelSize'<\/span>: self<\/span>.SQUAREWIDTH},\n        'fields'<\/span>: 'pixelSize'<\/span>\n    }\n})\nbody = {'requests'<\/span>: requests}\n\nsetwidthresponse = service.spreadsheets().batchUpdate(\n                        spreadsheetId=self<\/span>.SPREADSHEET_ID,\n                        body=body).execute()<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
        6. Describe the paint job with dataclasses<\/h3>\n\n\n\n
        The request that paints is updateCells<\/code>. It takes a range, a list of rows and, for each cell, a userEnteredFormat<\/code> holding a backgroundColorStyle<\/code>. Writing those nested dictionaries by hand for a whole photo is out of the question, so RequestDataClasses.py<\/code> models the request as dataclasses. I generated the first draft by pasting a small sample of the JSON into quicktype<\/a>.<\/p>\n\n\n
        from<\/span> dataclasses<\/span> import<\/span> dataclass<\/span>\nfrom<\/span> dataclasses_json<\/span> import<\/span> dataclass_json<\/span>\nfrom<\/span> typing<\/span> import<\/span> List<\/span>\n\n@dataclass_json<\/span>\n@dataclass\nclass Range:<\/span>\n    sheet_id:<\/span> int\n    start_row_index:<\/span> int\n    end_row_index:<\/span> int\n    start_column_index:<\/span> int\n    end_column_index:<\/span> int\n\n@dataclass_json\n@dataclass\nclass RGBColor:<\/span>\n    red:<\/span> int\n    green:<\/span> int\n    blue:<\/span> int\n\n@dataclass_json\n@dataclass\nclass BackgroundColorStyle:<\/span>\n    rgb_color:<\/span> RGBColor\n\n@dataclass_json\n@dataclass\nclass UserEnteredFormat:<\/span>\n    background_color_style:<\/span> BackgroundColorStyle\n\n@dataclass_json\n@dataclass\nclass Value:<\/span>\n    user_entered_format:<\/span> UserEnteredFormat\n\n@dataclass_json\n@dataclass\nclass Row:<\/span>\n    values:<\/span> List[Value]\n\n@dataclass_json\n@dataclass\nclass UpdateCellsClass:<\/span>\n    range:<\/span> Range\n    rows:<\/span> List[Row]\n    fields:<\/span> str\n\n@dataclass_json\n@dataclass\nclass Request:<\/span>\n    update_cells:<\/span> UpdateCellsClass\n\n@dataclass_json\n@dataclass\nclass UpdateCells:<\/span>\n    requests:<\/span> List[Request]<\/code><\/span>Code language:<\/span> CSS<\/span> (<\/span>css<\/span>)<\/span><\/small><\/pre>\n\n\n
        The @dataclass_json<\/code> decorator gives every class a to_json()<\/code> method. Two details worth knowing: the field names are snake_case, and the color fields are annotated int<\/code> even though they will hold fractions between 0 and 1 (Python does not enforce the annotation).<\/p>\n\n\n\n
        7. Turn every pixel into a cell<\/h3>\n\n\n\n
        ImageToJSON.py<\/code> loops over the image row by row and column by column. Each pixel’s red, green and blue values (0 to 255) are divided by 255, because the API wants each channel between 0 and 1. A tqdm<\/code> progress bar shows how far along the rows are, which helps on large images.<\/p>\n\n\n
        class RequestBuilder:\n\n    def ImageArrayToJSON(SheetID, image_array, width, height):\n\n        range1 = Range(sheet_id=SheetID, start_row_index=0,\n                       end_row_index=height+1,\n                       start_column_index=0,\n                       end_column_index=width+1)\n\n        rows = []\n\n        for rowid in trange(0, height, desc=\"Rows\", unit=\"Rows\"):\n\n            columns = []\n\n            for columnid in range(0, width):\n\n                # Current pixel value in RGB\n                pixel = image_array[rowid * width + columnid]\n\n                pixelcolor = RGBColor(red=pixel[0] \/ 255,\n                                      green=pixel[1] \/ 255,\n                                      blue=pixel[2] \/ 255)\n\n                bgcolor = BackgroundColorStyle(rgb_color=pixelcolor)\n\n                myvalue = Value(user_entered_format=UserEnteredFormat(\n                                    background_color_style=bgcolor))\n\n                columns.append(myvalue)\n\n            rows.append(Row(values=columns))\n\n        cells = UpdateCellsClass(range=range1, rows=rows,\n                                 fields='UserEnteredFormat')\n\n        request = Request(update_cells=cells)\n        updaterequest = UpdateCells(requests=[request])\n\n        return updaterequest.to_json()<\/code><\/span><\/pre>\n\n\n
        The real file also logs each cell and row through Python’s logging<\/code> module. That makes the log file large on big images, but it is handy when a request is rejected.<\/p>\n\n\n\n
        8. Send it in one batch request<\/h3>\n\n\n\n
        The builder returns a JSON string, but the API client wants a Python object, so json.loads<\/code> converts it back before the call.<\/p>\n\n\n
        requestSON = RequestBuilder.ImageArrayToJSON(self<\/span>.sheetID, self<\/span>.image_array,\n                                             self<\/span>.width, self<\/span>.height)\n\nrequest = json.loads(requestSON)\n\nresponse = service.spreadsheets().batchUpdate(\n                spreadsheetId=self<\/span>.SPREADSHEET_ID,\n                body=request).execute()<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
        9. Put it together<\/h3>\n\n\n\n
        Finally, the public method runs the three stages in order. Each stage has its own try\/except<\/code>, so a failure tells you which step broke (loading the image, adding the sheet, or updating the sheet) and stops there. The __main__<\/code> block writes a log file and takes the image path from the command line.<\/p>\n\n\n
        def<\/span> SaveImageToGoogleSheet<\/span>(self, imagepath: str)<\/span>:<\/span>\n\n    self.imagepath = imagepath\n\n    try<\/span>:\n        self.__LoadImage()\n    except<\/span> Exception as<\/span> inst:\n        print(\"Failed to load Image.\"<\/span>)\n        print(inst)\n        return<\/span>\n\n    try<\/span>:\n        self.__AddNewSheet()\n    except<\/span> Exception as<\/span> inst:\n        print(\"Failed to Add new sheet.\"<\/span>)\n        print(inst)\n        return<\/span>\n\n    try<\/span>:\n        self.__SaveImageArrayToGSheet()\n    except<\/span> Exception as<\/span> inst:\n        print(\"Failed to update Google sheet file.\"<\/span>)\n        print(inst)\n        traceback.print_exc()\n        return<\/span>\n\n\nif<\/span> __name__ == \"__main__\"<\/span>:\n\n    if<\/span>(len(sys.argv) <= 1<\/span>):\n        print(\"Please pass the file name\"<\/span>)\n    else<\/span>:\n        imageload = ImageToGoogleSheet()\n        imageload.SaveImageToGoogleSheet(sys.argv[1<\/span>])<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
        The repository also includes ImageToGoogleSheet.ipynb<\/code>, the same steps as notebook cells. That is the Jupyter demo from the talk. It also holds a sample image folder, including monasmall.png<\/code> (the Mona Lisa) and pyconv.png<\/code>.<\/p>\n\n\n\n
        What made painting images on Google Sheets hard<\/h2>\n\n\n\n
        Four things slowed me down, and they are the reason the code looks the way it does.<\/p>\n\n\n\n