Connect to a Book#

When reading/writing data to the active sheet, you don’t need a book object:

>>> import xlwings as xw
>>> xw.Range('A1').value = 'something'

Python to Excel#

The easiest way to connect to a book is offered by xw.Book: it looks for the book in all app instances and returns an error, should the same book be open in multiple instances. To connect to a book in the active app instance, use xw.books and to refer to a specific app, use:

>>> app = xw.App()  # or something like xw.apps[10559] for existing apps, get the available PIDs via xw.apps.keys()
>>> app.books['Book1']

Note that you usually should use App as a context manager as this will make sure that the Excel instance is closed and cleaned up again properly:

with xw.App() as app:
    book = app.books['Book1']



New book



Unsaved book



Book by (full)name



When specifying file paths on Windows, you should either use raw strings by putting an r in front of the string or use double back-slashes like so: C:\\path\\to\\file.xlsx.

Excel to Python (RunPython)#

To reference the calling book when using RunPython in VBA, use xw.Book.caller(), see Call Python with “RunPython”. Check out the section about Debugging to see how you can call a script from both sides, Python and Excel, without the need to constantly change between xw.Book.caller() and one of the methods explained above.

User Defined Functions (UDFs)#

Unlike RunPython, UDFs don’t need a call to xw.Book.caller(), see User Defined Functions (UDFs). You’ll usually use the caller argument which returns the xlwings range object from where you call the function.