Skip to content

In-cell pictures

EPPlus supports cell pictures - images inside a cell - from version 8, both local images and web images (images downloaded from an https url by the IMAGE function).

Local images

Local images are added via the new Picture property of a range.

Supported image types

The following image types are supported by EPPlus:

  • png
  • jpg
  • gif
  • bmp
  • webp
  • ico

Add or replace a local picture

Note that you also can use the Set method on multi-cell ranges. In that case the pictures will be added to all cells in the range.

// add via a byte array
var imageBytes = File.ReadAllBytes(@"c:\Temp\myImage.png");
worksheet.Cells["A1"].Picture.Set(imageBytes);
// add via a stream
var ms = new MemoryStream(imageBytes);
worksheet.Cells["A1"].Picture.Set(ms);
// or a file path
worksheet.Cells["A1"].Picture.Set(@"c:\Temp\myImage.png");
// or a FileInfo instance
var fileInfo = new FileInfo(@"c:\Temp\myImage.png");
worksheet.Cells["A1"].Picture.Set(fileInfo);

' add via a byte array
Dim imageBytes = File.ReadAllBytes("c:\Temp\myImage.png")
worksheet.Cells("A1").Picture.Set(imageBytes)
' add via a stream
Dim ms = New MemoryStream(imageBytes)
worksheet.Cells("A1").Picture.Set(ms)
' or a file path
worksheet.Cells("A1").Picture.Set("c:\Temp\myImage.png")
' or a FileInfo instance
Dim fileInfo = New FileInfo("c:\Temp\myImage.png")
worksheet.Cells("A1").Picture.Set(fileInfo)

The Set method also has overloads where you can set the alt-text of the image and mark it as decorative (these properties are used by screen readers).

worksheet.Cells["A1"].Picture.Set(imageBytes, "This is an alt text");
// or set decorative to true:
worksheet.Cells["A1"].Picture.Set(imageBytes, isDecorative: true);

worksheet.Cells("A1").Picture.Set(imageBytes, "This is an alt text")
' or set decorative to true:
worksheet.Cells("A1").Picture.Set(imageBytes, isDecorative:=True)

Read a local picture

var pic = sheet.Cells["A1"].Picture.Get();
// get the file name (the internal name used in the workbook, could be something like "image3.png")
string fileName = pic.FileName;
// get the image bytes
byte[] imageBytes = pic.GetImageBytes();
// get the picture type (LocalImage or WebImage)
ExcelCellPictureTypes picType = pic.PictureType;
// get the alt-text
string altText = pic.AltText;
// get the cell's address
OfficeOpenXml.ExcelAddress address = pic.CellAddress;

Dim pic = sheet.Cells("A1").Picture.Get()
' get the file name (the internal name used in the workbook, could be something like "image3.png")
Dim fileName As String = pic.FileName
' get the image bytes
Dim imageBytes As Byte() = pic.GetImageBytes()
' get the picture type (LocalImage or WebImage)
Dim picType As ExcelCellPictureTypes = pic.PictureType
' get the alt-text
Dim altText As String = pic.AltText
' get the cell's address
Dim address As OfficeOpenXml.ExcelAddress = pic.CellAddress

Check if a local picture exists

if(sheet.Cells["A1"].Picture.Exists)
{
   Console.WriteLine("There is a picture in A1!");
}

If sheet.Cells("A1").Picture.Exists Then
    Console.WriteLine("There is a picture in A1!")
End If

Remove a local picture

sheet.Cells["A1"].Picture.Remove();
// you can also remove all pictures within a range with multiple cells
sheet.Cells["A1:C5"].Picture.Remove();

sheet.Cells("A1").Picture.Remove()
' you can also remove all pictures within a range with multiple cells
sheet.Cells("A1:C5").Picture.Remove()

Local images in formula calculation

Local images are processed by the formula calculation in EPPlus. For example, this will add a local image in cell B1 and in cell C1.

// imageBytes is a byte array representing the image.
worksheet.Cells["A1"].Picture.Set(imageBytes);
worksheet.Cells["B1"].Formula = "A1";
worksheet.Cells["C1"].Formula = "IF(True(),A1,A2)";
worksheet.Calculate();

' imageBytes is a byte array representing the image.
worksheet.Cells("A1").Picture.Set(imageBytes)
worksheet.Cells("B1").Formula = "A1"
worksheet.Cells("C1").Formula = "IF(True(),A1,A2)"
worksheet.Calculate()

Local image cell value

If you access the Value property of a cell that contains a cell picture you will get an instance of the ExcelCellPicture class. This is the same class that is returned from the Picture.Get() method as described above.

Web images

Note that the IMAGE function is not supported on .NET 3.5. Web images can only be added by the IMAGE function, which is supported in the formula calculation from version 8.

// string url = "https://yoururl.com/yourimage.png"
sheet.Cells["A1"].Formula = $"IMAGE(\"{url}\")";
// the image will be downloaded and added to the cell during the calculation
sheet.Calculate();
var pic = sheet.Cells["A1"].Picture.Get();
// the picture can be read as the local image described above

' Dim url As String = "https://yoururl.com/yourimage.png"
sheet.Cells("A1").Formula = $"IMAGE(""{url}"")"
' the image will be downloaded and added to the cell during the calculation
sheet.Calculate()
Dim pic = sheet.Cells("A1").Picture.Get()
' the picture can be read as the local image described above

Downloading images

Note that per default EPPlus will only download images that do not exist in the workbook. Also images will only be downloaded once per url.

You can configure EPPlus to always refresh images the first time a unique url occurs:

ws.Calculate(x => x.AlwaysRefreshImageFunction = true);

ws.Calculate(Sub(x) x.AlwaysRefreshImageFunction = True)

IHttpService

The OfficeOpenXml.Interfaces.Net.IHttpService is a new interface available in the EPPlus.Interfaces NuGet package from version 8. It has only one method:

byte[] Download(string url);

Function Download(url As String) As Byte()

By default, the IMAGE function in EPPlus uses an implementation of this interface to fetch images via HTTPS with no additional configuration. You can replace this with your own implementation of the IHttpService interface like this:

using var package = new ExcelPackage();
IHttpService myHttpsService = new MyOwnHttpsService();
package.Settings.ImageFunctionService = myHttpsService;

Using package As New ExcelPackage()
    Dim myHttpsService As IHttpService = New MyOwnHttpsService()
    package.Settings.ImageFunctionService = myHttpsService
End Using

See also