xlsx-viewer-pro (Excel Viewer Pro)

🤝 Community, Issues & Support

• 🐛 Found a bug, formula calculation issue, or file parsing error? Please Open an Issue — reports are tracked and resolved quickly!
• 💬 Questions, formula additions, or GUI feature ideas? Join our GitHub Discussions.
• ⭐ Find xlsx-viewer-pro useful? Give it a star on GitHub — it helps more developers and analysts discover it!
• ☕ Support development (USDT TRC-20): TDVbEdnpgNgoAhNcn1EwXxWHiR3RKLit5P (Verify on TronScan)

A high-performance Python spreadsheet library, headless formula engine (129+ functions), native x64 SIMD SSE2 math engine, Native MCP Server (xlsx-mcp), and modern Office Ribbon desktop application for .xlsx, .xlsm, .xls, .csv, and .tsv files. Compatible with Python 3.8 to 3.16 (including Free-Threaded No-GIL 3.13t–3.16t and PyPy 3.8–3.12).

---

🧩 Universal Compatibility Matrix

Runtime / Implementation	Supported Versions	Execution Mode	Status
CPython (Standard)	3.8, 3.9, 3.10, 3.11, 3.12, 3.13, 3.14, 3.15, 3.16 (Alpha)	Bytecode + GIL	✅ Fully Supported
CPython (Free-Threaded)	3.13t, 3.14t, 3.15t, 3.16t (Alpha)	Multi-core No-GIL (PEP 703)	✅ Fully Supported
PyPy (JIT Accelerated)	3.8, 3.9, 3.10, 3.11, 3.12	High-speed JIT tracing	✅ Fully Supported
Operating Systems	Windows (7, 8, 10, 11), Linux, macOS (Intel & Apple Silicon)	x86_64 (SIMD SSE2), ARM64 (Pure Python Fallback)	✅ Fully Supported

---

⚡ Key Highlights

• 🧮 Headless Excel Formula Engine: Evaluate Excel formulas in pure Python without launching any UI. Supports 129 functions across Math, Trigonometry, Statistics, Finance (PMT, PV, FV, NPV, IRR), Lookups (VLOOKUP, XLOOKUP, INDEX, MATCH), Text, Logic, and Date/Time.
• 🚀 Hardware SIMD SSE2 Acceleration: Built-in 64-bit native assembly engine (xlsx_math64.dll) delivering up to 7.4+ million double-precision operations per second with automatic pure-Python fallback on non-Windows/ARM platforms.
• 🛠️ Dual-Use Architecture: Use it as a lightweight Python library, a command-line tool (xlsx-viewer-pro / xlsx-viewer / xv), or a full-featured desktop spreadsheet application.
• 🎨 Modern Desktop GUI: Office Ribbon UI with dynamic real-time status bar statistics (SUM, AVERAGE, COUNT, MIN, MAX), 10+ chart types, conditional formatting, auto-filter, and goal seek.
• 🧩 Zero Heavy Spreadsheet Engine Dependencies: No LibreOffice, COM, or Excel installation required.

---

📦 Installation

Platform / Manager	Installation Command
PyPI (Standard)	pip install xlsx-viewer-pro
PyPI (uv)	uv add xlsx-viewer-pro
Conda (Conda-Forge)	conda install -c conda-forge xlsx-viewer-pro | pixi add xlsx-viewer-pro
Ubuntu / Debian (APT PPA)	curl -sS https://eminsk.github.io/ppa/setup.sh | sudo bash sudo apt install python3-xlsx-viewer-pro
Ubuntu / Debian (.deb)	sudo dpkg -i python3-xlsx-viewer-pro_1.1.0-1_all.deb

Add to your project with uv (recommended):

uv add xlsx-viewer-pro

Or install via standard pip:

pip install xlsx-viewer-pro

You can also run the CLI instantly without installing using uvx:

uvx xlsx-viewer-pro --calc "=SUM(10, 20, 30) * 2"

⚡ Zero C-Build Requirements & Python 3.15 Ready

xlsx-viewer-pro installs in milliseconds with zero C build requirements by default (openpyxl + ttkbootstrap), and bundles pre-compiled standalone Flat Assembler (FASM) 64-bit DLLs for SIMD SSE2 math.

• Standard install (CLI, desktop viewer, 129 formula functions, SIMD SSE2):

  uv add xlsx-viewer-pro
  # or
  pip install xlsx-viewer-pro

• Optional charting support (Matplotlib Chart Wizard):

  uv add "xlsx-viewer-pro[charts]"
  # or
  pip install "xlsx-viewer-pro[charts]"

🧵 Free-Threaded (No-GIL / PEP 703) Verified

xlsx-viewer-pro is 100% verified on Python 3.13t, 3.14t, and 3.15t without GIL (-X gil=0). All 129 formula functions and the native x64 SIMD SSE2 FASM engine are fully thread-safe, enabling parallel formula evaluation across all CPU cores without GIL bottlenecks via standard ThreadPoolExecutor.

---

🐍 Python Library Quickstart

1. Headless Formula Evaluation

Evaluate any Excel formula directly from Python:

from xlsx_viewer import evaluate_formula

# Basic arithmetic & math
result = evaluate_formula("=SUM(10, 20, 30) * 2")
print(result)  # 120.0

# Financial formulas
monthly_payment = evaluate_formula("=PMT(0.05 / 12, 360, -250000)")
print(f"Monthly Mortgage: ${monthly_payment:.2f}")  # $1342.05

# Statistical & Logic
val = evaluate_formula("=IF(AVERAGE(85, 90, 92) >= 90, 'Honors', 'Standard')")
print(val)  # 'Honors'

2. Evaluating Formulas with Cell Context

Pass cell coordinate mappings directly using standard Excel notation:

from xlsx_viewer import evaluate_formula

context = {
    "A1": 15000,
    "A2": 3200,
    "B1": 0.15,
    "B2": "Tier-1",
}

# Reference cells directly
net_profit = evaluate_formula("=(A1 - A2) * (1 - B1)", context=context)
print(f"Net Profit: ${net_profit:.2f}")  # $10030.00

# Text and conditional logic with context
status = evaluate_formula(
    '=IF(A1 > 10000, CONCAT(B2, " - High Volume"), "Normal")',
    context=context,
)
print(status)  # 'Tier-1 - High Volume'

3. Using the FormulaEngine Class

For dynamic resolution or integrating with custom data sources:

from xlsx_viewer import FormulaEngine

# Custom resolver: fn(row: int, col: int, sheet: str | None) -> value
matrix = [
    [10, 20, 30],
    [40, 50, 60],
]


def custom_resolver(row: int, col: int, sheet: str | None = None):
    try:
        return matrix[row][col]
    except IndexError:
        return 0


engine = FormulaEngine(resolver=custom_resolver)
result = engine.evaluate("=SUM(A1:C2) + MAX(A1:C2)")
print(result)  # 210 + 60 = 270.0

4. SIMD Hardware-Accelerated Vector Math

Leverage native 64-bit SSE2 assembly routines for high-throughput calculations:

from xlsx_viewer.asm import (
    is_asm_available,
    simd_avg,
    simd_max,
    simd_min,
    simd_sum,
    simd_sumproduct,
)

print("SIMD SSE2 Active:", is_asm_available())

data_a = [10.5, 20.25, 30.75, 40.0, 50.5, 60.0]
data_b = [1.0, 2.0, 3.0, 4.0, 5.0, 6.0]

print("Sum:", simd_sum(data_a))
print("Average:", simd_avg(data_a))
print("Min / Max:", simd_min(data_a), simd_max(data_a))
print("Sumproduct:", simd_sumproduct(data_a, data_b))

5. In-Memory Workbook Data Models

Load, inspect, and manipulate Excel workbooks programmatically. If you don't have an existing workbook, you can create one with openpyxl or inspect any existing .xlsx file:

import openpyxl
from xlsx_viewer import load_workbook

# 1. Create a sample workbook if one doesn't exist
sample_wb = openpyxl.Workbook()
sample_sheet = sample_wb.active
sample_sheet.title = "Sheet1"
sample_sheet["A1"] = 100
sample_sheet["B1"] = 200
sample_wb.save("report.xlsx")

# 2. Load the workbook into xlsx-viewer
wb = load_workbook("report.xlsx")
print(f"Sheets: {wb.sheet_names}")

sheet = wb.get_sheet("Sheet1")
print(f"Dimensions: {sheet.max_row} rows x {sheet.max_col} cols")

# Read cell values and formulas
cell = sheet.get_cell(row=0, col=0)  # A1
if cell:
    print(f"A1 Value: {cell.value}, Formula: {cell.formula}")

# Modify cells in-memory
sheet.set_cell(row=0, col=1, value=1250.50)

---

💻 Command Line Interface (CLI)

Note: The commands below are terminal commands (PowerShell / CMD / Bash), not Python code. Run them directly in your shell or with uv run.

xlsx-viewer comes with a CLI tool accessible as both xlsx-viewer and xv:

# Evaluate an Excel formula from the terminal
xv --calc "=SUM(10, 20, 30) * 2"
# 120.0

# Calculate financial loan payment
xv -c "=PMT(0.065 / 12, 360, -350000)"
# 2212.24

# List all 129 supported Excel formula functions
xv --list-formulas

# Inspect environment and hardware SIMD acceleration status
xv --info

# Open a workbook in the desktop GUI
xv sample_report.xlsx

# Start Model Context Protocol (MCP) Server over stdio:
xlsx-mcp

(To invoke the CLI from inside a Python script, use from xlsx_viewer.cli import main; main(["--calc", "=SUM(10, 20)"]))

---

🤖 Native MCP (Model Context Protocol) Server

Connect xlsx-viewer-pro directly to Claude Desktop, Cursor, Windsurf, or Antigravity via the built-in xlsx-mcp (xv --mcp) JSON-RPC 2.0 server to give your AI assistant deterministic 129-function Excel formula calculation (XLOOKUP, PMT, IRR, SUMIFS) and headless .xlsx reading/writing (xlsx_evaluate_formula, xlsx_read_workbook, xlsx_write_cells, xlsx_list_formulas):

{
  "mcpServers": {
    "xlsx-engine": {
      "command": "xlsx-mcp"
    }
  }
}

---

🖥️ Desktop Application Features

Launch the desktop spreadsheet GUI with:

xlsx-viewer
# or
python -m xlsx_viewer

📊 Office Ribbon Navigation

• Home Tab: Undo/Redo, Clipboard (Cut, Copy, Paste, Paste Special), Font styling, Cell fill & text colors, Cell borders, Alignment & Wrap Text, Number formats ($, €, ₽, %, decimals), Conditional Formatting.
• Insert Tab: Chart Wizard (10+ chart types), Shapes, and Comments.
• Data Tab: Multi-level Sorting, AutoFilter with column search checkboxes, Remove Duplicates, Text-to-Columns, and Goal Seek.
• Formulas Tab: Function Wizard (fx), Precedence auditing, and calculation options (F9).
• View Tab: Gridline toggling, Zoom levels (50% – 200%), and Theme switcher.

📈 Chart Wizard (10+ Types)

Interactive charts powered by Matplotlib:

• Column & Bar Charts
• Line & Area Charts
• Pie & Donut Charts
• XY Scatter Plots & Histograms
• Professional color palettes: Excel Classic, Modern Teal, Vibrant, Pastel, Monochrome.

⌨️ Keyboard Shortcuts

Shortcut	Action
Ctrl + N	New Workbook
Ctrl + O	Open File
Ctrl + S	Save File
Ctrl + Shift + S	Save As...
Ctrl + Z / Ctrl + Y	Undo / Redo
Ctrl + C / Ctrl + X / Ctrl + V	Copy / Cut / Paste
Ctrl + A	Select Entire Sheet
Ctrl + F / Ctrl + H	Find / Replace
Ctrl + G	Go to Cell
F2 / Double Click	In-place Cell Editor
F9	Recalculate All Formulas
Shift + Arrow Keys	Expand Cell Selection
Tab / Enter	Move Right / Down

---

🧮 Supported Formula Functions (129 Total)

Click to expand full function list by category

📐 Math & Trigonometry (33)

SUM, SUMIF, SUMIFS, PRODUCT, ROUND, ROUNDUP, ROUNDDOWN, INT, TRUNC, ABS, MOD, POWER, SQRT, PI, RAND, RANDBETWEEN, CEILING, FLOOR, SIGN, SIN, COS, TAN, ASIN, ACOS, ATAN, DEGREES, RADIANS, EXP, LN, LOG, LOG10, FACT, SUMPRODUCT

📊 Statistical (20)

AVERAGE, AVERAGEA, AVERAGEIF, AVERAGEIFS, COUNT, COUNTA, COUNTBLANK, COUNTIF, COUNTIFS, MIN, MINIFS, MAX, MAXIFS, MEDIAN, MODE, STDEV, STDEVP, VAR, VARP, LARGE, SMALL, RANK

💰 Financial (9)

PMT, PV, FV, RATE, NPER, NPV, IRR, SLN, SYD

🔍 Lookup & Reference (11)

VLOOKUP, HLOOKUP, XLOOKUP, INDEX, MATCH, LOOKUP, CHOOSE, ROW, COLUMN, ROWS, COLUMNS

🔤 Text (23)

CONCAT, CONCATENATE, TEXTJOIN, LEFT, RIGHT, MID, LEN, TRIM, UPPER, LOWER, PROPER, EXACT, FIND, SEARCH, REPLACE, SUBSTITUTE, REPT, TEXT, VALUE, CHAR, CODE, CLEAN, T

⚖️ Logical (11)

IF, IFS, SWITCH, AND, OR, NOT, XOR, IFERROR, IFNA, TRUE, FALSE

📅 Date & Time (11)

TODAY, NOW, DATE, TIME, YEAR, MONTH, DAY, DAYS, EDATE, EOMONTH, WEEKDAY

ℹ️ Information (10)

ISBLANK, ISNUMBER, ISTEXT, ISNONTEXT, ISLOGICAL, ISERROR, ISERR, ISNA, TYPE, N

---

🏛️ Architecture

xlsx-viewer/
├── xlsx_viewer/            # Core Library Package
│   ├── __init__.py         # Public API exports
│   ├── api.py              # evaluate_formula, load_workbook, launch_gui
│   ├── cli.py              # CLI entrypoint (xlsx-viewer / xv)
│   ├── formulas.py         # Headless formula evaluation engine (129 functions)
│   ├── models.py           # In-memory workbook, sheet, cell, and formatting models
│   ├── formatting.py       # Number, date, currency, and conditional formatting
│   ├── widgets.py          # Tkinter / ttkbootstrap UI widgets (Ribbon, Sheet, Grid)
│   ├── dialogs.py          # Wizards (Chart, Function, Filter, Goal Seek)
│   ├── config.py           # Styling, themes, and configuration
│   └── asm/                # Hardware acceleration
│       ├── xlsx_math64.dll # Native x64 SSE2 assembly DLL
│       └── asm_bridge.py   # ctypes bridge with fallback
├── tests/                  # Integration and Unit Test Suite (44 tests)
│   ├── test_app.py
│   ├── test_enhanced_features.py
│   ├── test_library_api.py
│   └── test_mcp.py
├── asm/                    # Standalone 64-bit Assembly Spreadsheet Engine
│   ├── xlsx_gui64.asm      # 100% Native x86-64 GUI Spreadsheet (FASM)
│   ├── xlsx_gui64.exe      # Compiled standalone Windows 64-bit binary (~44KB)
│   ├── xlsx_math64.asm     # Vectorized SIMD SSE2 math engine (DLL)
│   ├── xlsx_math64.dll     # Compiled acceleration DLL
│   └── test_asm.py         # Hardware SIMD test & benchmark suite
├── pyproject.toml          # PEP 517 / 621 Build Specification
└── README.md

---

⚡ Standalone 64-bit Assembly Spreadsheet (asm/xlsx_gui64.exe)

For extreme performance, zero-runtime environments, and bare-metal Windows execution, xlsx-viewer-pro includes a 100% native x86-64 assembly spreadsheet application written in Flat Assembler (FASM):

• Zero Runtime Dependencies: Pure Win32 PE64 binary (~44 KB), requiring no Python, .NET, C runtime, or external DLLs.
• Office Ribbon & Menus: Active 8-category menu bar (File, Edit, View, Insert, Format, Formulas, Data, Help) with full keyboard shortcuts (Ctrl+N, Ctrl+O, Ctrl+S, Ctrl+C, Ctrl+V, Ctrl+Z, Ctrl+Y, Ctrl+F, F2, F5, F9).
• Live Font & Formatting: Dynamic Font Family (Segoe UI, Calibri, Arial, Consolas), Font Size (8 through 16 pt, A+, A-), Bold, Italic, Underline, and Number Formats ($, ₽, %, comma decimals).
• Multi-Sheet Data Persistence: Interactive Sheet1, Sheet2, Sheet3, and [+] Add Sheet tabs with full cell memory isolation and persistence across tab switching.
• Formula Bar & Evaluator: Subclassed live formula bar with [fx] evaluator supporting =SUM(range), =AVG(range), =MIN(range), =MAX(range), =COUNT(range), and arithmetic expressions (+, -, *, /).
• Tabular Multi-Cell Clipboard: Intelligent clipboard parser handling both single cell and tab/CRLF-delimited multi-cell range copy/paste.
• Building with FASM:

  fasm asm/xlsx_gui64.asm asm/xlsx_gui64.exe
  fasm asm/xlsx_math64.asm asm/xlsx_math64.dll

---

🧪 Running Tests

Run the full test suite with pytest:

uv run pytest -v
# or with standard pytest
pytest -v

All 44 tests pass with 100% success rate across Python 3.8 through 3.16 (including No-GIL free-threaded 3.13t–3.16t) and PyPy 3.8 through 3.12.

---

🌐 High-Performance Systems Ecosystem

xlsx-viewer-pro is developed by @eminsk as part of an open-source AI & systems engineering ecosystem:

• ⚡ NanoVector — Bare-metal C99/AVX2 vector search & episodic memory engine (~120KB) with Native MCP Server (pip install nanovector).
• 🧠 AgentJIT — Just-In-Time Compiler for AI Agent Trajectories with speculative de-optimization guards (pip install agentjit).
• ⚡ NanoGEMM — Bare-metal AVX2+FMA SIMD matrix multiplication engine in ~100KB for sub-microsecond CPU inference (pip install nanogemm).
• 🖥️ NanoRecall — 100% Private, offline desktop memory & semantic screen search engine powered by NanoVector (pip install nanorecall).
• 🛒 avito-sdk — Headless Avito scraping & data extraction SDK with price drop tracking, Playwright cookies, Telegram/VK bots, and Native MCP Server (pip install avito-sdk).
• 📈 yfinance-ta-patterns — Candlestick & chart pattern scanner with AI Confluence Scoring, Backtesting, and Native MCP Server (pip install yfinance-ta-patterns).

---

☕ Support, Community & Donations

If you find this project valuable and would like to support ongoing development:

• ⭐ Star the Repository: If xlsx-viewer-pro speeds up your spreadsheets and formula calculations, give us a star on GitHub — it helps more developers discover headless Excel tools!
• 💬 Join Discussions: Have ideas, use cases, or new Excel functions to request? Start or join a thread in GitHub Discussions!
• ☕ Donate (USDT TRC-20):
  TDVbEdnpgNgoAhNcn1EwXxWHiR3RKLit5P
  (Network: TRON / TRC-20 | Verify on TronScan)

---

📄 License

This project is licensed under the MIT License.

---

👤 Author

Developed by eminsk (GitHub) • M_N_Nik@yahoo.com