Introduction

In EPPlus, number formatting controls how Excel displays a value without changing the underlying numeric data. That distinction matters because a cell can still contain the same decimal, date serial number, or currency amount even though it appears differently to the user.

Most formatting work in EPPlus comes down to setting Style.Numberformat.Format with either a built-in Excel-style pattern or a custom format string. Once you understand that pattern language, formatting becomes predictable.

The Core EPPlus API

The main property you use is worksheet.Cells[row, column].Style.Numberformat.Format.

1using OfficeOpenXml;
2using System.IO;
3
4ExcelPackage.LicenseContext = LicenseContext.NonCommercial;
5
6using var package = new ExcelPackage();
7var sheet = package.Workbook.Worksheets.Add("Report");
8
9sheet.Cells[1, 1].Value = 1234.567;
10sheet.Cells[1, 1].Style.Numberformat.Format = "0.00";
11
12package.SaveAs(new FileInfo("report.xlsx"));

The cell still contains the numeric value 1234.567, but Excel displays it as 1234.57 because the format rounds the display to two decimal places.

Common Format Strings

Excel format strings are reused by EPPlus, so the same patterns you know from Excel generally apply here.

Examples:

• '0 for integer-style display'
• '0.00 for two decimal places'
• '#,##0 for thousands separators'
• '#,##0.00 for grouped decimals'
• '0% or 0.00% for percentages'
• 'yyyy-mm-dd for date display'
• '$#,##0.00 for currency-style output'

Example with several formats:

1sheet.Cells[2, 1].Value = 42;
2sheet.Cells[2, 1].Style.Numberformat.Format = "0";
3
4sheet.Cells[3, 1].Value = 0.256;
5sheet.Cells[3, 1].Style.Numberformat.Format = "0.00%";
6
7sheet.Cells[4, 1].Value = 1234567.89;
8sheet.Cells[4, 1].Style.Numberformat.Format = "#,##0.00";

Dates Are Numbers Too

Excel stores dates internally as serial numbers. EPPlus follows that model, so a date format only affects presentation.

sheet.Cells[5, 1].Value = new DateTime(2026, 3, 11);
sheet.Cells[5, 1].Style.Numberformat.Format = "yyyy-mm-dd";

Without a date format, Excel may show the raw serial number instead of a human-readable date.

That is one of the most common surprises for new EPPlus users.

Custom Formatting Is Often Better Than Converting to Strings

A tempting mistake is to pre-format values as strings in C# before writing them to Excel. That makes the spreadsheet look right, but it destroys the numeric type and prevents Excel from sorting, filtering, and calculating properly.

Prefer this:

sheet.Cells[1, 1].Value = 1999.95;
sheet.Cells[1, 1].Style.Numberformat.Format = "$#,##0.00";

Not this:

sheet.Cells[1, 1].Value = "$1,999.95";

The first cell is numeric with display formatting. The second is just text.

Reuse Styles for Large Sheets

If you format many cells individually, performance can degrade. A better pattern is to apply formatting to ranges or columns.

sheet.Column(2).Style.Numberformat.Format = "#,##0.00";
sheet.Column(3).Style.Numberformat.Format = "yyyy-mm-dd";

This is cleaner and more efficient than formatting thousands of cells one by one.

Handling Locale Expectations

Excel format strings use Excel’s formatting rules, not your current C# culture settings. That means a format like #,##0.00 describes the style, while Excel will render separators based on the user’s environment.

If your export has strict locale expectations, test the resulting workbook in the target Excel environment instead of assuming the display will look identical everywhere.

Common Pitfalls

A common mistake is writing already-formatted strings instead of numeric values. That makes later calculations and sorting harder or impossible.

Another mistake is forgetting to format dates, which leads Excel to display serial numbers rather than calendar values.

Developers also mix C# formatting assumptions with Excel formatting syntax. EPPlus uses Excel-style format patterns, not decimal.ToString(...) format strings.

Finally, be careful with large sheets. Applying per-cell styling unnecessarily can slow generation significantly.

Summary

• EPPlus number formatting controls display, not the underlying cell value.
• Use Style.Numberformat.Format with Excel-style format strings.
• Keep numbers as numbers and dates as dates instead of converting them to strings.
• Apply styles to ranges or columns when possible for better performance.
• Test date, currency, and locale-sensitive exports in real Excel when formatting accuracy matters.