Skip to content
agent-xlsx

Installation

agent-xlsx requires Python 3.10+. All data commands work with zero system dependencies. Screenshot and recalc commands need a rendering engine (Aspose or LibreOffice).

Zero install. Runs directly like npx:

uvx agent-xlsx probe spreadsheet.xlsx
uvx agent-xlsx read spreadsheet.xlsx "A1:F50"
uvx agent-xlsx search spreadsheet.xlsx "revenue" --ignore-case

Global install

Install once, use everywhere:

# uv (recommended)
uv tool install agent-xlsx

# pipx
pipx install agent-xlsx

Then use directly:

agent-xlsx probe spreadsheet.xlsx

pip

Add to a project or virtual environment:

pip install agent-xlsx

Agent Skill

Give AI agents built-in knowledge of agent-xlsx commands and workflows:

npx skills add apetta/agent-xlsx

Compatible with Claude Code, Cursor, Gemini CLI, and 20+ other agents.

Docker

With Aspose (lightweight, no LibreOffice)

FROM python:3.12-slim

# Aspose system deps for rendering on Linux
RUN apt-get update && \
    apt-get install -y --no-install-recommends libgdiplus libfontconfig1 fonts-liberation && \
    apt-get clean && rm -rf /var/lib/apt/lists/*

RUN pip install agent-xlsx aspose-cells-python

# Optional: set Aspose licence
# COPY Aspose.Cells.lic /app/
# ENV ASPOSE_LICENSE_PATH=/app/Aspose.Cells.lic

RUN agent-xlsx --help

With LibreOffice (free, larger image)

FROM python:3.12-slim

RUN apt-get update && \
    apt-get install -y --no-install-recommends libreoffice-calc && \
    apt-get clean && rm -rf /var/lib/apt/lists/*

RUN pip install agent-xlsx

RUN agent-xlsx --help

Rendering engines

Aspose.Cells is included as a dependency and works out of the box for screenshot and recalc commands (in evaluation mode). For watermark-free rendering, set a licence. Alternatively, install LibreOffice as a free option.

Aspose.Cells (cross-platform, no Excel/LibreOffice needed)

Aspose.Cells is bundled with agent-xlsx. Without a licence, it runs in evaluation mode (watermarks, 100-file-per-session limit).

Note: Aspose.Cells for Python is commercially licensed, not covered by this project's Apache-2.0 licence.

# Set licence
agent-xlsx license --set /path/to/Aspose.Cells.lic
# Or via environment variable
export ASPOSE_LICENSE_PATH=/path/to/Aspose.Cells.lic

LibreOffice (free fallback)

# macOS
brew install --cask libreoffice

# Ubuntu / Debian
apt install libreoffice-calc

# Alpine
apk add libreoffice-calc