{"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":"python","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,"search_vec":"'0.35.1':56 'activ':48 'allow':23 'autom':17,59 'bsd':6 'bsd-licens':5 'call':26 'current':53 'data':20 'defin':38 'enabl':16 'excel':15,29,57 'frequent':51 'function':39 'interact':12 'librari':9,46 'licens':7 'maco':44 'macro':35 'maintain':49 'manipul':21 'microsoft':14,60 'offic':61 'power':19 'python':8,27 'releas':52 'script':34 'simplifi':11 'spreadsheet':58 'support':33 'udf':40 'user':24,37 'vba':62 'versa':32 'version':55 'vice':31 'window':42 'xlwing':1,2","created_at":"2026-04-12T16:54:02.274988+00:00","updated_at":"2026-04-17T14:07:44.901337+00:00","problems":[{"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.","cause":"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.","error":"Failed to import xlwings"},{"fix":"Access the range's value first before applying string methods: `sheet.range('A1').value.upper()`.","cause":"A string method like `upper()` is being called directly on an `xlwings.Range` object instead of its actual `value`.","error":"AttributeError: 'Range' object has no attribute 'upper'"},{"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.","cause":"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.","error":"PermissionError: [Errno 13] Permission denied"},{"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)`.","cause":"The `xlwings` script is trying to connect to or interact with an Excel application instance that is not currently active or running.","error":"xlwings.exceptions.AppNotOpenError: Excel is not running."},{"fix":"pip install xlwings","cause":"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.","error":"ModuleNotFoundError: No module named 'xlwings'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.36.17","cli_name":"","cli_version":null,"type":"library","homepage":"https://www.xlwings.org","github":"https://github.com/xlwings/xlwings","docs":"https://docs.xlwings.org","changelog":"https://docs.xlwings.org/en/stable/whatsnew.html","pypi":"https://pypi.org/project/xlwings/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["data","database","serialization","communication"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-30","next_check":"2026-07-28","install_tag":null}}