xlwings

Warnings

• breaking The `@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.
• breaking The `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')`.
• gotcha xlwings (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.
• gotcha When 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.
• gotcha A 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.
• gotcha The 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.

Install

• pip install xlwings Install with pip
• conda install -c conda-forge xlwings Install with conda (conda-forge)

Imports

• xlwings

  import xlwings as xw

Quickstart

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.")