0
# xlwings
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: xlwings
7
- **Language**: Python
8
- **Installation**: `pip install xlwings`
9
- **Version**: 0.33.15
10
- **Platforms**: Windows, macOS, Web (Office.js via PRO)
11
- **Python**: 3.9+ required
12

13
## Core Imports
14

15
```python
16
import xlwings as xw
17
```
18

19
Common patterns for working with Excel:
20

21
```python
22
# Direct access to main API
23
from xlwings import App, Book, Sheet, Range
24

25
# Access collections
26
from xlwings import apps, books, sheets
27

28
# For UDFs (Windows only)
29
from xlwings import func, sub, arg, ret
30
```
31

32
## Basic Usage
33

34
```python
35
import xlwings as xw
36

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

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

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

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

55
# Save and close
56
wb.save('/path/to/workbook.xlsx')
57
wb.close()
58
app.quit()
59
```
60

61
## Architecture
62

63
xlwings uses an **Engine abstraction** that supports multiple Excel backends:
64

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

71
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.
72

73
## Capabilities
74

75
### Core Excel Objects
76

77
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.
78

79
```python { .api }
80
class App:
81
    def __init__(self, visible=None, spec=None, add_book=True, xl=None): ...
82
    def activate(self): ...
83
    def calculate(self, calculation=None): ...
84
    def kill(self): ...
85
    def quit(self): ...
86
    @property
87
    def books(self) -> Books: ...
88
    @property
89
    def calculation(self) -> str: ...
90
    @property
91
    def display_alerts(self) -> bool: ...
92
    @property
93
    def screen_updating(self) -> bool: ...
94
    @property
95
    def visible(self) -> bool: ...
96
    @property
97
    def version(self) -> VersionNumber: ...
98

99
class Book:
100
    def activate(self): ...
101
    def close(self): ...
102
    def save(self, path=None): ...
103
    def fullname(self) -> str: ...
104
    def json(self): ...
105
    @property
106
    def app(self) -> App: ...
107
    @property
108
    def name(self) -> str: ...
109
    @property
110
    def sheets(self) -> Sheets: ...
111
    @property
112
    def names(self) -> Names: ...
113
    @property
114
    def selection(self) -> Range: ...
115

116
class Sheet:
117
    def activate(self): ...
118
    def clear(self): ...
119
    def delete(self): ...
120
    def copy(self, before=None, after=None): ...
121
    def range(self, cell1, cell2=None) -> Range: ...
122
    @property
123
    def book(self) -> Book: ...
124
    @property
125
    def name(self) -> str: ...
126
    @property
127
    def charts(self) -> Charts: ...
128
    @property
129
    def pictures(self) -> Pictures: ...
130
    @property
131
    def shapes(self) -> Shapes: ...
132
    @property
133
    def used_range(self) -> Range: ...
134

135
class Range:
136
    def clear(self): ...
137
    def clear_contents(self): ...
138
    def copy(self, destination=None): ...
139
    def paste(self, paste=None): ...
140
    def delete(self, shift=None): ...
141
    def end(self, direction): ...
142
    def expand(self, mode='table'): ...
143
    def offset(self, row_offset=0, column_offset=0): ...
144
    def resize(self, nrows=None, ncols=None): ...
145
    def merge(self, across=False): ...
146
    @property
147
    def value(self): ...
148
    @value.setter
149
    def value(self, data): ...
150
    @property
151
    def formula(self) -> str: ...
152
    @property
153
    def formula_array(self) -> str: ...
154
    @property
155
    def address(self) -> str: ...
156
    @property
157
    def column(self) -> int: ...
158
    @property
159
    def row(self) -> int: ...
160
    @property
161
    def shape(self) -> tuple: ...
162
    @property
163
    def size(self) -> int: ...
164
    @property
165
    def width(self) -> float: ...
166
    @property
167
    def height(self) -> float: ...
168
    @property
169
    def color(self): ...
170
    @property
171
    def current_region(self) -> Range: ...
172
```
173

174
[Core Excel Objects](./core-objects.md)
175

176
### Collections and Module Functions
177

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

180
```python { .api }
181
# Collections
182
apps: Apps  # Collection of all App instances
183
books: Books  # Collection of all Book instances  
184
sheets: Sheets  # Collection of all Sheet instances
185
engines: Engines  # Collection of available Excel engines
186

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

192
[Collections and Functions](./collections-functions.md)
193

194
### User Defined Functions (UDFs)
195

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

198
```python { .api }
199
def func(f=None, *, category: str = None, volatile: bool = False, 
200
         call_in_wizard: bool = True, macro_type: str = None): ...
201
def sub(f=None, *, call_in_wizard: bool = True): ...
202
def arg(convert=None, *, ndim: int = None, transpose: bool = False): ...
203
def ret(convert=None, *, transpose: bool = False, expand: str = None): ...
204

205
def serve(): ...
206
def import_udfs(module_name: str): ...
207
def get_udf_module(module_name: str): ...
208
```
209

210
[User Defined Functions](./udfs.md)
211

212
### Data Conversion System
213

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

216
```python { .api }
217
# Converter classes available in xlwings.conversion
218
class Converter:
219
    def __init__(self, **options): ...
220
    def read_value(self, value, options): ...
221
    def write_value(self, value, options): ...
222

223
class RawConverter(Converter): ...
224
class DictConverter(Converter): ...  
225
class NumpyArrayConverter(Converter): ...
226
class PandasDataFrameConverter(Converter): ...
227
class PandasSeriesConverter(Converter): ...
228
```
229

230
[Data Conversion](./conversion.md)
231

232
### Charts and Visualization
233

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

236
```python { .api }
237
class Chart:
238
    def delete(self): ...
239
    def to_pdf(self, path: str): ...
240
    def to_png(self, path: str): ...
241
    @property
242
    def name(self) -> str: ...
243
    @property
244
    def chart_type(self): ...
245
    @property
246
    def source_data(self) -> Range: ...
247

248
class Picture:
249
    def delete(self): ...
250
    def update(self, image): ...
251
    @property
252
    def name(self) -> str: ...
253
    @property
254
    def left(self) -> float: ...
255
    @property
256
    def top(self) -> float: ...
257
    @property
258
    def width(self) -> float: ...
259
    @property
260
    def height(self) -> float: ...
261

262
class Shape:
263
    def delete(self): ...
264
    def duplicate(self): ...
265
    @property
266
    def name(self) -> str: ...
267
    @property
268
    def type(self): ...
269
    @property
270
    def left(self) -> float: ...
271
    @property
272
    def top(self) -> float: ...
273
    @property
274
    def width(self) -> float: ...
275
    @property
276
    def height(self) -> float: ...
277
```
278

279
[Charts and Visualization](./charts-visualization.md)
280

281
### Utility Functions
282

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

285
```python { .api }
286
def to_datetime(xldate: float, datemode: int = 0): ...
287

288
# Additional utilities in xlwings.utils
289
def prepare_xl_data_value(value): ...
290
def get_duplicates(seq): ...
291
def np_datetime_to_xl(np_date): ...
292
def pd_datetime_to_xl(pd_date): ...
293
def datetime_to_xl(dt): ...
294
```
295

296
[Utility Functions](./utilities.md)
297

298
### Constants and Enumerations
299

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

302
```python { .api }
303
# Example constant classes (254 total available)
304
from xlwings.constants import (
305
    ChartType, XlChartType,
306
    Direction, InsertShiftDirection,
307
    FileFormat, XlFileFormat,
308
    RGBColor, ColorIndex,
309
    HAlign, VAlign,
310
    ObjectHandleIcons  # Available in top-level namespace
311
)
312
```
313

314
[Constants and Enumerations](./constants.md)
315

316
### Command Line Interface
317

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

320
```python { .api }
321
# Available via 'xlwings' command
322
# Key commands:
323
# xlwings quickstart <project_name>
324
# xlwings addin install/remove  
325
# xlwings runpython <script>
326
# xlwings restapi run
327
# xlwings auth <action>
328
# xlwings license <action>
329
# xlwings code embed/extract
330
# xlwings release
331
```
332

333
[Command Line Interface](./cli.md)
334

335
### PRO Features  
336

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

339
```python { .api }
340
# Reports (xlwings.reports)
341
def create_report(template_path: str, output_path: str, **data): ...
342
def render_template(template: str, **data): ...
343

344
# Server integration (xlwings.server)  
345
def script(f): ...
346
def func(f): ...
347
def arg(*args, **kwargs): ...
348
def ret(*args, **kwargs): ...
349

350
# Embedded code (xlwings.pro.embedded_code)
351
def dump(code: str, book: Book): ...
352
def load(book: Book) -> str: ...
353
```
354

355
[PRO Features](./pro-features.md)
356

357
## Types
358

359
```python { .api }
360
# Core types
361
Apps = Collection[App]
362
Books = Collection[Book] 
363
Sheets = Collection[Sheet]
364
Charts = Collection[Chart]
365
Pictures = Collection[Picture]
366
Shapes = Collection[Shape]
367
Names = Collection[Name]
368
Engines = Collection[Engine]
369
RangeColumns = Collection
370
RangeRows = Collection
371

372
# Utility types
373
class VersionNumber:
374
    """Excel version number with major/minor properties."""
375
    @property
376
    def major(self) -> int: ...
377
    @property
378
    def minor(self) -> int: ...
379

380
# Exception hierarchy
381
class XlwingsError(Exception): ...
382
class LicenseError(XlwingsError): ...
383
class ShapeAlreadyExists(XlwingsError): ...
384
class NoSuchObjectError(XlwingsError): ...
385
```