Quick start

Installing with Enthought Canopy

Enthought Canopy provides an integrated PyXLL egg that you can install via the Package Manager. You must upgrade to Canopy v1.3 for PyXLL to install correctly. You can upgrade Canopy under the Help menu.

  1. Launch the Package Manager from the Canopy Welcome Screen.

  2. Select Available Packages and search for pyxll.

  3. Select the pyxll package from the list and click the Install button to the right to have Canopy download and install PyXLL for you.

  4. Launch a Canopy Command Prompt from the Start -> Enthought Canopy menu.

  5. Launch Canopy and open the pyxll.cfg file by entering:

    edit_pyxll_configuration
    

Installing with other Python Distributions

  1. Unpack the .zip file you’ve downloaded.
  2. Open pyxll.cfg in a text editor.

Configuration

Either way you’ve installed PyXLL, if you’ve followed the steps above you will now have the config file open. Make the following changes:

  1. Set the log path and file to wherever you want the log to go.
  2. 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)
  3. Set modules to the name of the Python module you will be putting your code in.

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**

Writing some Python code

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

Installing the Excel Addin

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. For later versions of Excel click the top left circle in Excel 2007 or File menu in Excel 2010 and 2013 and go to Options -> Add-Ins -> Manage Excel Addins and browse for the pyxll.xll file and add it.

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

Trying it out

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.

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.