Registry / data / xlwings

xlwings

JSON →
library0.36.17pypypi✓ verified 22d ago

xlwings is a BSD-licensed Python library that simplifies interaction with Microsoft Excel, enabling automation and powerful data manipulation. It allows users to call Python from Excel and vice versa, supporting scripting, macros, and User Defined Functions (UDFs) on Windows and macOS. The library is actively maintained with frequent releases, currently at version 0.35.1.

pip install xlwings
INSTALL
IMPORT
SIG · XLWINGS
X
xlwings
datapythonv0.36.17
Install
2.2s avg
Import
155ms
Disk
20MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.36.17 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.166s · 22.8MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 2.2s · import 0.144s · 23MB
20MB installed
● package 20MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

xlwings
import xlwings as xw

This quickstart demonstrates how to programmatically control Excel from Python. It shows how to launch Excel in the background, create a new workbook, write and read cell values, and properly close the application. It requires an existing Excel installation.

import xlwings as xw # Start an Excel app (visible=False runs it in the background) # xlwings (Open Source) requires Excel to be installed on the machine. try: app = xw.App(visible=False) # Open an existing workbook or create a new one # wb = app.books.open("path/to/my_workbook.xlsx") wb = app.books.add() # Create a new, empty workbook sheet = wb.sheets # Write a value to cell A1 sheet.range('A1').value = 'Hello from xlwings!' # Read a value from cell A1 cell_value = sheet.range('A1').value print(f"Value in A1: {cell_value}") # Write a 2D list to a range (will expand automatically) sheet.range('A3').value = [['Header1', 'Header2'],,] # Save the workbook (optional) # wb.save("my_output.xlsx") # print("Workbook saved as my_output.xlsx") finally: # Ensure Excel app is quit even if errors occur if 'app' in locals() and app.alive: wb.close() # Close the workbook (without saving if not explicitly saved) app.quit() print("Excel application quit.")
Debug
Known issues
breakingThe `@sub` decorator used for exposing Python functions to Excel VBA has been renamed to `@script` in v0.35.0 to align with xlwings Lite. `@sub` is now deprecated.
fix
Replace `@xlwings.sub` with `@xlwings.script` in your Python code.
affects: >=0.35.0
breakingThe `range.insert()` method now explicitly requires the `shift` argument. The previous default behavior of letting Excel guess the shift direction is no longer supported.
fix
When using `range.insert()`, provide the `shift` argument, e.g., `sheet.range('A1').insert(shift='down')` or `sheet.range('A1').insert(shift='right')`.
affects: >=0.30.3
gotchaxlwings (Open Source) fundamentally requires a local installation of Microsoft Excel on Windows or macOS to function. It does not work standalone for file manipulation on Linux without additional xlwings PRO or Server components.
fix
Ensure Microsoft Excel is installed on the machine where xlwings scripts are run. Consider xlwings PRO or xlwings Server for Linux or Excel-less environments.
affects: All versions
gotchaWhen calling Python functions from Excel VBA via `RunPython`, placing `xw.Book.caller()` outside the called function (e.g., as a global variable) can prevent Excel from shutting down properly, leading to 'zombie' Excel processes, especially when `Use UDF Server = True` is active.
fix
Always place `xw.Book.caller()` directly within the Python function that is invoked by Excel VBA.
affects: All versions
gotchaA bug existed where xlwings conflicted with Microsoft's new Python in Excel feature (introduced by `=PY()`). This required users to re-import User-defined functions (UDFs) after upgrading to resolve conflicts.
fix
If encountering issues with UDFs and Python in Excel, ensure you have the latest xlwings version (0.35.1+) and re-import your UDFs after upgrading.
affects: 0.35.0 (and potentially earlier versions used with Python in Excel)
gotchaThe xlwings Excel add-in's version must match the installed xlwings Python package version. Mismatches can lead to unexpected behavior or errors.
fix
After upgrading the `xlwings` Python package, run `xlwings addin install` from your command prompt to update the Excel add-in.
affects: All versions
Errors
Common errors & fixes
Failed to import xlwings
The xlwings add-in cannot find or correctly load the Python interpreter or the `xlwings` package from the specified Python environment when called from Excel VBA.
fix
Ensure `xlwings` is installed in the Python environment linked by the add-in. Verify the 'PYTHON_WIN' or 'PYTHON_MAC' path in the xlwings add-in settings (Ribbon > xlwings > xlwings Settings) points to the correct `python.exe` or `python` executable.
AttributeError: 'Range' object has no attribute 'upper'
A string method like `upper()` is being called directly on an `xlwings.Range` object instead of its actual `value`.
fix
Access the range's value first before applying string methods: `sheet.range('A1').value.upper()`.
PermissionError: [Errno 13] Permission denied
The Python script is attempting to access (e.g., open, save, delete) an Excel file that is currently open in another application or for which the user lacks sufficient file system permissions.
fix
Close the target Excel file in any open applications or ensure the script has the necessary read/write permissions for the file and its directory.
xlwings.exceptions.AppNotOpenError: Excel is not running.
The `xlwings` script is trying to connect to or interact with an Excel application instance that is not currently active or running.
fix
Ensure an Excel application is running before attempting to connect to an active instance, or explicitly start a new Excel instance using `xw.App(visible=True)`.
ModuleNotFoundError: No module named 'xlwings'
The xlwings library is not installed in the Python environment being used, or the Python interpreter used by your IDE/system doesn't have it installed.
fix
pip install xlwings
Upgrade
Version history
0.36.17latest on PyPI · released Aug 17, 2026
Audit
Dependencies
pywin32requiredRequired for Excel automation on Windows. Automatically installed by pip/conda.
appscriptrequiredRequired for Excel automation on macOS. Automatically installed by pip/conda.
psutilrequiredRequired for process utilities on macOS. Automatically installed by pip/conda.
Agent activity
77 hits · last 30 days
node
70
OpenAI (training)
1
Resources