Getting Started

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.7.4 or 2.x 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
    

This is where you can update your configuration with any Python modules you want to load, and any other settings (see Configuration).

Once configured, start Excel and the PyXLL addin will be loaded.

Installing with other Python Distributions

  1. Download the standalone PyXLL zip file from here.

    Make sure you download the correct version depending on the versions of Python and Excel you want to use.

  2. Unpack the zipfile.

    PyXLL can be used with any Python distribution. Depending on how you have Python installed on your system you may need to configure PyXLL so it knows where to find your Python installation.

    PyXLL is packaged as a zip file. Simply unpack the zip file where you want PyXLL to be installed, there is no installer to run.

  3. Edit the config file

    Once you’ve unzipped the PyXLL download the next thing to do is to edit the pyxll.cfg file. Any text editor will do for this. The default configuration may be fine for you while you’re getting started, and you can come back to it later if you want to make any changes.

    If your Python installation is not configured to be the default Python installation (this is common with Anaconda and PortablePython distributions) you will need set the following in your config file

    [PYTHON]
    executable = <path to your python.exe>
    
  1. Install the addin

    Once you’re happy with the configuration you can install the addin in Excel by following the instructions below.

    • Excel 2010 - 2016

      Select the File menu in Excel and go to Options -> Add-Ins -> Manage Excel Addins and browse for the folder you unpacked PyXLL to and select pyxll.xll.

    • Excel 2007

      Click the large circle at the top left of Excel and go to Options -> Add-Ins -> Manage Excel Addins and browse for the folder you unpacked PyXLL to and select pyxll.xll.

    • Excel 97 - 2003

      Go to Tools -> Add-Ins -> Browse and locate pyxll.xll in the folder you unpacked the zip file to.

_images/add_addin.png
  1. Optional Install the PyXLL stubs package

    If you are using a Python IDE that provides autocompletion or code checking, because the pyxll module isn’t installed, you may find it complains and won’t be able to provide any autocompletion for functions imported from the pyxll module.

    In the downloaded zip file you will find a .whl file. The exact filename varies depending on the version of PyXLL you’ve downloaded. That’s a Python Wheel containing a dummy pyxll module that you can use for the purposes of keeping your IDE from complaining, and for writing code that depends on the pyxll module that you want to use outside of Excel (e.g. when unit testing).

    To install the wheel run the following command (substituting the actual wheel filename) from a command line:

    > pip install {pyxll wheel filename}
    

    The real pyxll module is compiled into the pyxll.xll addin.

    If you are using a version of Python that isn’t supported by pip all you need to do is to unzip the wheel file into your Python site-packages folder (the wheel file is simply a zip file with a different file extension).

Calling a Python Function in Excel

One of the main features of PyXLL is being able to call a Python function from a formula in an Excel workbook.

First start by creating a new Python module and writing a simple Python function. To expose that function to Excel all you have to do is to apply the xl_func decorator to it.:

from pyxll import xl_func

@xl_func
def hello(name):
    return "Hello, %s" % name

Save your module and edit the pyxll.cfg file again to add your new module to the list of modules to load and add the directory containing your module to the pythonpath.

[PYXLL]
modules = <add your new module here>

[PYTHON]
pythonpath = <add the folder containing your Python code here>

Reload PyXLL by going to the Addins menu in Excel and selecting PyXLL -> Reload.

Now in a worksheet you can type a formula using your new Python function.:

=hello("me")

If you make any mistakes in your code or your function returns an error you can check the log file to find out what the error was, make and necessary changes to your code and reload PyXLL again.

_images/quickstart-func.png

Next Steps

The user guide has comprehensive coverage of how to use all the features of PyXLL and a quick look through there will quickly bring you up to speed on how to do most things with PyXLL.

Many of PyXLL’s features are demonstrated in the examples included in download. These are a good place to start to learn more about what PyXLL can do.

More example code can be found on PyXLL’s GitHub page.

If there is anything specifically you’re trying to achieve and can’t find an example or help in the user guide please contact us and we will do our best to help.