{"id":5099,"library":"xlwings","title":"xlwings","description":"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.","status":"active","version":"0.35.1","language":"en","source_language":"en","source_url":"https://github.com/xlwings/xlwings","tags":["excel","spreadsheet","automation","microsoft office","vba"],"install":[{"cmd":"pip install xlwings","lang":"bash","label":"Install with pip"},{"cmd":"conda install -c conda-forge xlwings","lang":"bash","label":"Install with conda (conda-forge)"}],"dependencies":[{"reason":"Required for Excel automation on Windows. Automatically installed by pip/conda.","package":"pywin32","optional":false},{"reason":"Required for Excel automation on macOS. Automatically installed by pip/conda.","package":"appscript","optional":false},{"reason":"Required for process utilities on macOS. Automatically installed by pip/conda.","package":"psutil","optional":false}],"imports":[{"symbol":"xlwings","correct":"import xlwings as xw"}],"quickstart":{"code":"import xlwings as xw\n\n# Start an Excel app (visible=False runs it in the background)\n# xlwings (Open Source) requires Excel to be installed on the machine.\ntry:\n    app = xw.App(visible=False)\n    \n    # Open an existing workbook or create a new one\n    # wb = app.books.open(\"path/to/my_workbook.xlsx\")\n    wb = app.books.add() # Create a new, empty workbook\n    sheet = wb.sheets\n\n    # Write a value to cell A1\n    sheet.range('A1').value = 'Hello from xlwings!'\n\n    # Read a value from cell A1\n    cell_value = sheet.range('A1').value\n    print(f\"Value in A1: {cell_value}\")\n\n    # Write a 2D list to a range (will expand automatically)\n    sheet.range('A3').value = [['Header1', 'Header2'],,]\n\n    # Save the workbook (optional)\n    # wb.save(\"my_output.xlsx\")\n    # print(\"Workbook saved as my_output.xlsx\")\n\nfinally:\n    # Ensure Excel app is quit even if errors occur\n    if 'app' in locals() and app.alive:\n        wb.close() # Close the workbook (without saving if not explicitly saved)\n        app.quit()\n        print(\"Excel application quit.\")","lang":"python","description":"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."},"warnings":[{"fix":"Replace `@xlwings.sub` with `@xlwings.script` in your Python code.","message":"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.","severity":"breaking","affected_versions":">=0.35.0"},{"fix":"When using `range.insert()`, provide the `shift` argument, e.g., `sheet.range('A1').insert(shift='down')` or `sheet.range('A1').insert(shift='right')`.","message":"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.","severity":"breaking","affected_versions":">=0.30.3"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always place `xw.Book.caller()` directly within the Python function that is invoked by Excel VBA.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"0.35.0 (and potentially earlier versions used with Python in Excel)"},{"fix":"After upgrading the `xlwings` Python package, run `xlwings addin install` from your command prompt to update the Excel add-in.","message":"The xlwings Excel add-in's version must match the installed xlwings Python package version. Mismatches can lead to unexpected behavior or errors.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}