Quick start

Unpack the archive you’ve downloaded and open pyxll.cfg in a text editor. Set the log path and file to wherever you want the log to go and change pythonpath [1] to where you’re going to put your Python modules (this may be the same as where you’ve extracted the archive to for now), and set modules to your Python module. We’ll write that Python module next.

If you have a license key you should copy it to the license section (see the config section for more details). If you do not have a license key you may still use PyXLL for non-commercial or evaulation purposes, but you will see a PyXLL pop-up dialog each time you start Excel.

Example config file:

[LOG]
verbosity = debug
path = c:/logs
file = pyxll.log
format = %(asctime)s - %(levelname)s : %(message)s

[PYXLL]
pythonpath = c:/my_python_modules
modules = my_xl_addin_module,my_other_xl_addin_module
developer_mode = 1

[LICENSE]
key = **put your license key here if you have one**
file = **or the path of your license file here**

Now create the python module that you specified in the config file using a text editor (in my example, the file will be called my_xl_addin_module.py).

First of all import xl_func from the pyxll module. The pyxll module is compiled into the PyXLL addin so does not need to be included in the pythonpath. Write a simple function that takes a string and returns a string, as shown in the example file below.

The python function needs to be decorated using the xl_func decorator in order for the PyXLL addin to expose it to Excel. The decorator takes one mandatory argument and several option arguments (as described in the xl_func section). The mandatory argument is the function signature which should specify the argument types and names (names are optional) and the return type. The return type is optional, and if not specified the default return type var will be used. var is a special type that can be used to pass any of the standard types. For more information about types see Standard argument and return types.

Example python module:

from pyxll import xl_func

@xl_func("string name: string")
def hello(name):
    """return a familiar greeting"""
    return "Hello, %s" % name

Now we’re ready to use that function in Excel! Start Excel and add the PyXLL addin. If you’re using Excel 97-2003 go to Tools -> Add-Ins -> Browse and locate pyxll.xll and add it. If you’re using Excel 2007-2010 click the top left circle and go to options -> Add-Ins -> Manage Excel Addins and browse for the pyxll.xll file and add it.

New in PyXLL 1.3

PyXLL looks for the python dll in the same folder as itself first before trying to find it in the system path.

If at this stage you get an error saying that Python is not installed or the Python dll can’t be found, the most likely problem is that you don’t have the correct Python version installed on your PC. The Python version you have installed must match whatever version of PyXLL you downloaded (currently versions 2.3 to 2.7 are available). Install the correct version and try again. It’s important that python2x.dll (where x is whatever version of python you’re using) is in your system path (if you use one of the standard binary distributions of python it will already have been automatically installed somewhere in your system path).

You should now be able to enter the formula =hello("me") and see the calculated value “Hello, me”. If you look in the function browser in Excel you should see your function in the PyXLL category with your docstring as the help text for the function. Using other categories for your functions is covered in the xl_func section.

Using Eclipse and PyDev?

You can interactively debug Python code running in PyXLL with Eclipse and PyDev by attaching the PyDev debugger. See this example for details.

If your function doesn’t work, check the log file, which you will find in the directory you specified in the config file. If you have made any errors in your python module you will see those in the log file. Correct those errors and select the ‘Reload PyXLL’ menu item from the PyXLL Addin menu. This will either be in the main menu bar if you’re using a version of Excel before 2007, or in the AddIns ribbon menu for 2007 and later versions.

Footnotes

[1]	Your system pythonpath must also be setup so PyXLL can find the standard modules. The pythonpath in the config is only for additional paths.