Go Excelize Quick Start

Introduction to Excelize

Excelize is a basic library for manipulating Office Excel documents written in Go language, based on the international standards ECMA-376 and ISO/IEC 29500. It can be used to read and write spreadsheet documents created by Microsoft Excel™ 2007 and above, supporting various document formats such as XLAM / XLSM / XLSX / XLTM / XLTX. It is highly compatible with documents containing styles, images (tables), pivot tables, slicers, and other complex components, and provides a streaming read-write API for processing workbooks with large-scale data. It can be applied to various report platforms, cloud computing, edge computing, and other systems. Using this library requires Go language version 1.16 or higher.

Installation

The table below lists the minimum requirements of Excelize basic library for different versions of Go language:

Using the latest version of Excelize requires Go language version 1.16 or higher. Please note that there are incompatible changes in Go 1.21.0, which causes the Excelize basic library to not work properly on this version. If you are using Go 1.21.x, please upgrade to Go 1.21.1 or higher.

• Installation Command

go get github.com/xuri/excelize

• If you are using Go Modules to manage packages, use the following command to install the latest version.

go get github.com/xuri/excelize/v2

Update

• Update Command

go get -u github.com/xuri/excelize/v2

Create Excel Documents

Below is a simple example of creating an Excel document:

package main

import (
    "fmt"
    "github.com/xuri/excelize/v2"
)

func main() {
    f := excelize.NewFile()
    defer func() {
        if err := f.Close(); err != nil {
            fmt.Println(err)
        }
    }()
    // Create a new sheet
    index, err := f.NewSheet("Sheet2")
    if err != nil {
        fmt.Println(err)
        return
    }
    // Set cell values
    f.SetCellValue("Sheet2", "A2", "Hello world.")
    f.SetCellValue("Sheet1", "B2", 100)
    // Set the default worksheet of the workbook
    f.SetActiveSheet(index)
    // Save the file to the specified path
    if err := f.SaveAs("Book1.xlsx"); err != nil {
        fmt.Println(err)
    }
}

Read Excel Documents

The following is an example of reading Excel documents:

package main

import (
    "fmt"

    "github.com/xuri/excelize/v2"
)

func main() {
    f, err := excelize.OpenFile("Book1.xlsx")
    if err != nil {
        fmt.Println(err)
        return
    }
    defer func() {
        if err := f.Close(); err != nil {
            fmt.Println(err)
        }
    }()
    // Get the value of a specified cell in the worksheet
    cell, err := f.GetCellValue("Sheet1", "B2")
    if err != nil {
        fmt.Println(err)
        return
    }
    fmt.Println(cell)
    // Get all cells on Sheet1
    rows, err := f.GetRows("Sheet1")
    if err != nil {
        fmt.Println(err)
        return
    }
    for _, row := range rows {
        for _, colCell := range row {
            fmt.Print(colCell, "\t")
        }
        fmt.Println()
    }
}

Create Charts in Excel Documents

It's very simple to create charts using Excelize, requiring only a few lines of code. You can build charts based on existing data in the worksheet or add data to the worksheet and then create charts.

package main

import (
    "fmt"

    "github.com/xuri/excelize/v2"
)

func main() {
    f := excelize.NewFile()
    defer func() {
        if err := f.Close(); err != nil {
            fmt.Println(err)
        }
    }()
    for idx, row := range [][]interface{}{
        {nil, "Apple", "Orange", "Pear"}, {"Small", 2, 3, 3},
        {"Normal", 5, 2, 4}, {"Large", 6, 7, 8},
    } {
        cell, err := excelize.CoordinatesToCellName(1, idx+1)
        if err != nil {
            fmt.Println(err)
            return
        }
        f.SetSheetRow("Sheet1", cell, &row)
    }
    if err := f.AddChart("Sheet1", "E1", &excelize.Chart{
        Type: excelize.Col3DClustered,
        Series: []excelize.ChartSeries{
            {
                Name:       "Sheet1!$A$2",
                Categories: "Sheet1!$B$1:$D$1",
                Values:     "Sheet1!$B$2:$D$2",
            },
            {
                Name:       "Sheet1!$A$3",
                Categories: "Sheet1!$B$1:$D$1",
                Values:     "Sheet1!$B$3:$D$3",
            },
            {
                Name:       "Sheet1!$A$4",
                Categories: "Sheet1!$B$1:$D$1",
                Values:     "Sheet1!$B$4:$D$4",
            }},
        Title: []excelize.RichTextRun{
            {
                Text: "Fruit 3D Clustered Column Chart",
            },
        },
    }); err != nil {
        fmt.Println(err)
        return
    }
    // Save the file to the specified path
    if err := f.SaveAs("Book1.xlsx"); err != nil {
        fmt.Println(err)
    }
}

Insert images into an Excel document

package main

import (
    "fmt"
    _ "image/gif"
    _ "image/jpeg"
    _ "image/png"

    "github.com/xuri/excelize/v2"
)

func main() {
    f, err := excelize.OpenFile("Book1.xlsx")
    if err != nil {
        fmt.Println(err)
        return
    }
    defer func() {
        if err := f.Close(); err != nil {
            fmt.Println(err)
        }
    }()
    // Insert an image
    if err := f.AddPicture("Sheet1", "A2", "image.png", nil); err != nil {
        fmt.Println(err)
        return
    }
    // Insert an image into the worksheet and set the scale of the image
    if err := f.AddPicture("Sheet1", "D2", "image.jpg",
        &excelize.GraphicOptions{ScaleX: 0.5, ScaleY: 0.5}); err != nil {
        fmt.Println(err)
        return
    }
    // Insert an image into the worksheet and set the print properties of the image
    enable, disable := true, false
    if err := f.AddPicture("Sheet1", "H2", "image.gif",
        &excelize.GraphicOptions{
            PrintObject:     &enable,
            LockAspectRatio: false,
            OffsetX:         15,
            OffsetY:         10,
            Locked:          &disable,
        }); err != nil {
        fmt.Println(err)
        return
    }
    // Save the file
    if err = f.Save(); err != nil {
        fmt.Println(err)
    }
}