PyXLL The Python Excel Add-In
  • Product
    • Features
    • Get Started
    • Request Demo
    • Download
  • Pricing
  • Resources
    • Documentation
    • Blog
    • Videos
    • FAQ
    • Learn Python
    • Customer Portal
    • About Us
  • Support
    • Documentation
    • Videos
    • FAQ
    • Contact Us
  • Contact Us
Table of Contents
  • PyXLL Documentation
  • Getting Started with PyXLL
    • Install PyXLL
    • Write your first Excel function
    • Explore the built-in examples
    • Troubleshooting
    • Next Steps
  • User Guide
  • Video Guides and Tutorials
  • API Reference
  • What’s new in PyXLL 5
  • Changelog
Close

Getting Started with PyXLL¶

PyXLL is an Excel add-in that lets you write Excel worksheet functions, macros, and more using Python. This guide takes you from a fresh install to your first working Python function in Excel.

Installing PyXLL using the command line tool

How to install PyXLL

Watch Video

Calling Python functions from Excel as worksheet functions

Excel Worksheet Functions (UDFs) in Python

Watch Video

Deploying Python Excel PyXLL add-ins

Deploying your PyXLL Add-in

Watch Video

Install PyXLL¶

Open a command prompt, activate your Python virtual environment if necessary, and run:

pip install pyxll

Followed by:

pyxll install

and follow the on-screen instructions.

  • When asked whether you have already downloaded PyXLL, enter n and the installer will download the right version for you.

  • You do not need a license key. When asked if you have a license key, enter n and the free 30 day trial will begin automatically when the add-in loads.

For other installation options (including manual installation) see the installation guide.

pyxll command not recognized?

pip install pyxll installs the pyxll command into your Python scripts folder, but if the Python scripts folder isn’t on your path then the command won’t be found.

Instead, run python -m pyxll install. This will do the same thing, without needing the pyxll command to be installed on your system path.

Write your first Excel function¶

Once PyXLL is installed you can expose a Python function to Excel in four steps.

Step 1: Create a Python module¶

Create a new file, for example my_functions.py, containing a function decorated with @xl_func:

from pyxll import xl_func

@xl_func
def hello(name):
    """Say hello to someone."""
    return "Hello, " + name

Step 2: Tell PyXLL to load your module¶

Open the PyXLL config file. The config file is the file named pyxll.cfg in the folder where you installed the PyXLL add-in. You can edit this with any text editor, such as notepad, or your Python code editor.

If you are not sure where the file is located, you can run pyxll status and that will tell you, or you can run pyxll config to open the config file using the associated editor.

The file is split into multiple sections. Look for the [PYTHON] section and in there you will find the pythonpath setting. This is a list of folders where Python will look for modules. Add the folder where you saved your new my_functions.py file so that it can be imported.

Next, look for the [PYXLL] section. In that section you will find the modules list. This is the list of Python modules (or packages) that will be loaded by the PyXLL add-in. Add your module name (my_functions) to this list. Note that a Python module name does not include the .py file extension.

[PYTHON]
pythonpath = C:\path\to\folder\containing\my_functions

[PYXLL]
modules = my_functions

Step 3: Reload PyXLL in Excel¶

In Excel, open the PyXLL menu and select Reload. This picks up your new module without restarting Excel.

Each time your open Excel, your configured modules are loaded automatically.

If there are any errors at this stage, check the PyXLL log file

By default it is in the logs folder inside your PyXLL installation directory. You can run pyxll status to find where PyXLL is installed if you are not sure where that is.

Step 4: Call your function from a cell¶

In any worksheet cell type:

=hello("World")
A simple Python function called from an Excel cell.

The Worksheet Functions section of the user guide explains the full range of what you can do with @xl_func, including type hints, array functions, and optional arguments.

Explore the built-in examples¶

The PyXLL installation includes an examples folder with an Excel workbook and Python source files demonstrating all major features — worksheet functions, macros, real-time data, plotting, ribbon toolbars, and more.

Open examples.xlsx to see them in action, and read the corresponding .py files to understand how each one works. Use pyxll status if you cannot remember where PyXLL was installed.

Troubleshooting¶

  • pip or the download fails due to a corporate firewall or proxy

    Follow the manual installation instructions instead.

  • “The ‘pyxll’ command is not recognised” after pip install

    Your Python Scripts folder may not be on your system path. Use python -m pyxll install instead - it works identically.

  • “pythonXXX.dll not found” when starting Excel

    The PyXLL add-in was built for a different Python version. Let the command-line installer download the correct version by entering n when asked if you have already downloaded PyXLL.

  • Other issues

    Check the PyXLL log file for the full error and Python stack trace. Search the FAQ or contact us for further help.

Next Steps¶

  • User Guide — complete documentation of all PyXLL features

  • Video Guides and Tutorials — video tutorials covering installation, worksheet functions, and more

  • API Reference — full Python API reference

« PyXLL Documentation
User Guide »
  • Home
  • Product
  • Features
  • Documentation
  • Download
  • Pricing
  • Support
  • Documentation
  • Videos
  • FAQ
  • Learn Python
  • Contact Us
  • About
  • About Us
  • Legal
  • Blog
© Copyright PyXLL Ltd