or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

charts-visualization.mdcli.mdcollections-functions.mdconstants.mdconversion.mdcore-objects.mdindex.mdpro-features.mdudfs.mdutilities.md
tile.json

tessl/pypi-xlwings

Python library for seamless bidirectional communication between Python and Excel across Windows and macOS platforms.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/xlwings@0.33.x

To install, run

npx @tessl/cli install tessl/pypi-xlwings@0.33.0

index.mddocs/

xlwings

Python library for seamless bidirectional communication between Python and Excel across Windows and macOS platforms. xlwings enables three primary integration modes: scripting for automating Excel from Python, macros for replacing VBA code with Python implementations, and User Defined Functions (UDFs) for creating custom Excel functions in Python.

Package Information

  • Package Name: xlwings
  • Language: Python
  • Installation: pip install xlwings
  • Version: 0.33.15
  • Platforms: Windows, macOS, Web (Office.js via PRO)
  • Python: 3.9+ required

Core Imports

import xlwings as xw

Common patterns for working with Excel:

# Direct access to main API
from xlwings import App, Book, Sheet, Range

# Access collections
from xlwings import apps, books, sheets

# For UDFs (Windows only)
from xlwings import func, sub, arg, ret

Basic Usage

import xlwings as xw

# Open Excel application and create new workbook
app = xw.App(visible=True)
wb = app.books.add()
ws = wb.sheets[0]

# Write data to Excel
ws.range('A1').value = 'Hello xlwings!'
ws.range('A2:C4').value = [[1, 2, 3], [4, 5, 6], [7, 8, 9]]

# Read data from Excel
data = ws.range('A2:C4').value
print(data)  # [[1.0, 2.0, 3.0], [4.0, 5.0, 6.0], [7.0, 8.0, 9.0]]

# Work with pandas DataFrames
import pandas as pd
df = pd.DataFrame({'A': [1, 2, 3], 'B': [4, 5, 6]})
ws.range('E1').value = df

# Save and close
wb.save('/path/to/workbook.xlsx')
wb.close()
app.quit()

Architecture

xlwings uses an Engine abstraction that supports multiple Excel backends:

  • Excel Engine (COM): Direct Windows Excel automation via pywin32
  • AppleScript Engine: macOS Excel automation via appscript
  • Remote Engine (PRO): Server-based Excel access via xlwings Server
  • Office.js Engine (PRO): Web Excel integration for browser-based automation
  • Calamine Engine (PRO): High-performance Excel file reading via Rust

The Conversion system provides flexible data transformation between Python and Excel, with built-in support for pandas DataFrames, NumPy arrays, nested lists, and custom converters.

Capabilities

Core Excel Objects

Primary classes for interacting with Excel applications, workbooks, worksheets, and cell ranges. These form the foundation of xlwings' object model and provide the main interface for Excel automation.

class App:
    def __init__(self, visible=None, spec=None, add_book=True, xl=None): ...
    def activate(self): ...
    def calculate(self, calculation=None): ...
    def kill(self): ...
    def quit(self): ...
    @property
    def books(self) -> Books: ...
    @property
    def calculation(self) -> str: ...
    @property
    def display_alerts(self) -> bool: ...
    @property
    def screen_updating(self) -> bool: ...
    @property
    def visible(self) -> bool: ...
    @property
    def version(self) -> VersionNumber: ...

class Book:
    def activate(self): ...
    def close(self): ...
    def save(self, path=None): ...
    def fullname(self) -> str: ...
    def json(self): ...
    @property
    def app(self) -> App: ...
    @property
    def name(self) -> str: ...
    @property
    def sheets(self) -> Sheets: ...
    @property
    def names(self) -> Names: ...
    @property
    def selection(self) -> Range: ...

class Sheet:
    def activate(self): ...
    def clear(self): ...
    def delete(self): ...
    def copy(self, before=None, after=None): ...
    def range(self, cell1, cell2=None) -> Range: ...
    @property
    def book(self) -> Book: ...
    @property
    def name(self) -> str: ...
    @property
    def charts(self) -> Charts: ...
    @property
    def pictures(self) -> Pictures: ...
    @property
    def shapes(self) -> Shapes: ...
    @property
    def used_range(self) -> Range: ...

class Range:
    def clear(self): ...
    def clear_contents(self): ...
    def copy(self, destination=None): ...
    def paste(self, paste=None): ...
    def delete(self, shift=None): ...
    def end(self, direction): ...
    def expand(self, mode='table'): ...
    def offset(self, row_offset=0, column_offset=0): ...
    def resize(self, nrows=None, ncols=None): ...
    def merge(self, across=False): ...
    @property
    def value(self): ...
    @value.setter
    def value(self, data): ...
    @property
    def formula(self) -> str: ...
    @property
    def formula_array(self) -> str: ...
    @property
    def address(self) -> str: ...
    @property
    def column(self) -> int: ...
    @property
    def row(self) -> int: ...
    @property
    def shape(self) -> tuple: ...
    @property
    def size(self) -> int: ...
    @property
    def width(self) -> float: ...
    @property
    def height(self) -> float: ...
    @property
    def color(self): ...
    @property
    def current_region(self) -> Range: ...

Core Excel Objects

Collections and Module Functions

Collections for managing multiple Excel objects and module-level functions for high-level operations like loading data and viewing in Excel.

# Collections
apps: Apps  # Collection of all App instances
books: Books  # Collection of all Book instances  
sheets: Sheets  # Collection of all Sheet instances
engines: Engines  # Collection of available Excel engines

# Module functions
def load(json: dict, sheet: Sheet = None, header: bool = True, index: bool = True): ...
def view(data, sheet_name: str = None): ...

Collections and Functions

User Defined Functions (UDFs)

Decorators and functions for creating custom Excel functions and subroutines in Python. Supports both Windows COM server and Office.js implementations.

def func(f=None, *, category: str = None, volatile: bool = False, 
         call_in_wizard: bool = True, macro_type: str = None): ...
def sub(f=None, *, call_in_wizard: bool = True): ...
def arg(convert=None, *, ndim: int = None, transpose: bool = False): ...
def ret(convert=None, *, transpose: bool = False, expand: str = None): ...

def serve(): ...
def import_udfs(module_name: str): ...
def get_udf_module(module_name: str): ...

User Defined Functions

Data Conversion System

Flexible framework for converting data between Python and Excel formats, with built-in support for pandas, NumPy, and custom conversion pipelines.

# Converter classes available in xlwings.conversion
class Converter:
    def __init__(self, **options): ...
    def read_value(self, value, options): ...
    def write_value(self, value, options): ...

class RawConverter(Converter): ...
class DictConverter(Converter): ...  
class NumpyArrayConverter(Converter): ...
class PandasDataFrameConverter(Converter): ...
class PandasSeriesConverter(Converter): ...

Data Conversion

Charts and Visualization

Classes for creating and manipulating Excel charts, including support for matplotlib figure integration and chart customization.

class Chart:
    def delete(self): ...
    def to_pdf(self, path: str): ...
    def to_png(self, path: str): ...
    @property
    def name(self) -> str: ...
    @property
    def chart_type(self): ...
    @property
    def source_data(self) -> Range: ...

class Picture:
    def delete(self): ...
    def update(self, image): ...
    @property
    def name(self) -> str: ...
    @property
    def left(self) -> float: ...
    @property
    def top(self) -> float: ...
    @property
    def width(self) -> float: ...
    @property
    def height(self) -> float: ...

class Shape:
    def delete(self): ...
    def duplicate(self): ...
    @property
    def name(self) -> str: ...
    @property
    def type(self): ...
    @property
    def left(self) -> float: ...
    @property
    def top(self) -> float: ...
    @property
    def width(self) -> float: ...
    @property
    def height(self) -> float: ...

Charts and Visualization

Utility Functions

Helper functions for data type conversion, configuration management, and Excel-specific operations like date/time handling.

def to_datetime(xldate: float, datemode: int = 0): ...

# Additional utilities in xlwings.utils
def prepare_xl_data_value(value): ...
def get_duplicates(seq): ...
def np_datetime_to_xl(np_date): ...
def pd_datetime_to_xl(pd_date): ...
def datetime_to_xl(dt): ...

Utility Functions

Constants and Enumerations

Complete Excel constants coverage with 254 constant classes providing access to all Excel enumerations and built-in values.

# Example constant classes (254 total available)
from xlwings.constants import (
    ChartType, XlChartType,
    Direction, InsertShiftDirection,
    FileFormat, XlFileFormat,
    RGBColor, ColorIndex,
    HAlign, VAlign,
    ObjectHandleIcons  # Available in top-level namespace
)

Constants and Enumerations

Command Line Interface

Comprehensive CLI for project setup, VBA integration, Excel add-in management, and deployment operations.

# Available via 'xlwings' command
# Key commands:
# xlwings quickstart <project_name>
# xlwings addin install/remove  
# xlwings runpython <script>
# xlwings restapi run
# xlwings auth <action>
# xlwings license <action>
# xlwings code embed/extract
# xlwings release

Command Line Interface

PRO Features

Commercial features including reports system, embedded code, additional engines, and xlwings Server integration.

# Reports (xlwings.reports)
def create_report(template_path: str, output_path: str, **data): ...
def render_template(template: str, **data): ...

# Server integration (xlwings.server)  
def script(f): ...
def func(f): ...
def arg(*args, **kwargs): ...
def ret(*args, **kwargs): ...

# Embedded code (xlwings.pro.embedded_code)
def dump(code: str, book: Book): ...
def load(book: Book) -> str: ...

PRO Features

Types

# Core types
Apps = Collection[App]
Books = Collection[Book] 
Sheets = Collection[Sheet]
Charts = Collection[Chart]
Pictures = Collection[Picture]
Shapes = Collection[Shape]
Names = Collection[Name]
Engines = Collection[Engine]
RangeColumns = Collection
RangeRows = Collection

# Utility types
class VersionNumber:
    """Excel version number with major/minor properties."""
    @property
    def major(self) -> int: ...
    @property
    def minor(self) -> int: ...

# Exception hierarchy
class XlwingsError(Exception): ...
class LicenseError(XlwingsError): ...
class ShapeAlreadyExists(XlwingsError): ...
class NoSuchObjectError(XlwingsError): ...