jupyter_function

Before you begin

1. Install JupyterExcel in your Jupyter server and Python kernel environments, configure the asset directory and URLs, and load the generated manifest in Excel. Follow the setup guide.
2. Put the examples in a notebook visible to the Jupyter server and save it to regenerate the add-in metadata.
3. If the managed JupyterExcel kernel is already running, restart it to load saved code changes, or use the JupyterExcel save-and-reload toolbar command. Saving alone updates metadata, not the running definitions.
4. Reload the add-in to pick up new functions or actions and enter your access token through the Token command.

The managed kernel executes code cells in discovered export notebooks when it initializes. Use trusted notebooks and avoid unintended top-level side effects.

Your first worksheet function

@jupyter_function exposes a Python function as an Excel formula. Return the value directly. The Python function remains callable normally in the notebook.

from jupyterexcel import jupyter_function

@jupyter_function
def add_tax(amount, rate):
    """Return the amount including tax."""
    return amount * (1 + rate)

In Excel, enter =Jupyter.add_tax(100, 0.08). The result is 108. You can also use =Jupyter.add_tax(B2, C2) when B2 contains 100 and C2 contains 8%.

These examples assume the default namespace, Jupyter. Replace it with your configured JUPYTEREXCEL_NAMESPACE when necessary.

Name, description, and types

from jupyterexcel import jupyter_function

@jupyter_function(
    name="Add",
    description="Add two numbers.",
    parameter_types={"a": "number", "b": "number"},
    result_type="number",
)
def add(a, b=0):
    return a + b

=Jupyter.Add(2, 3) returns 5. The Python default makes b optional; =Jupyter.Add(2) returns 2.

Use literal decorator values so the notebook scanner can read them without executing Python. Type metadata describes the Excel interface; it does not convert Python values or validate every incoming value. Both @jupyter_function and @jupyter_function() are supported.

Accept a range and return a table

from jupyterexcel import jupyter_function

@jupyter_function(
    name="DoubleRange",
    description="Double every number in a range.",
    parameter_types={"values": "number"},
    parameter_dimensionality={"values": "matrix"},
    result_type="number",
    result_dimensionality="matrix",
)
def double_range(values):
    return [[value * 2 for value in row] for row in values]

Put 1 and 2 in A1:B1 and 3 and 4 in A2:B2. Enter =Jupyter.DoubleRange(A1:B2) in D1. The result spills into D1:E2 as 2, 4 / 6, 8. Keep the spill area empty. This example expects numeric input cells.

Accept a variable number of values

from jupyterexcel import jupyter_function

@jupyter_function(
    name="SumNumbers",
    parameter_types={"values": "number"},
    result_type="number",
)
def sum_numbers(*values):
    return sum(values)

=Jupyter.SumNumbers(1, 2, 3) returns 6. The final Python *values parameter becomes an Excel repeating parameter. Keyword parameters after it are unsupported.

Results and troubleshooting

• Return JSON-compatible scalars or rectangular nested lists. Convert DataFrames and NumPy objects to supported Python values before returning them.
• Use synchronous functions; async def is not supported for execution.
• Keep worksheet functions focused on calculating results. Use an action when the user needs a form, a preview, or an explicit write to cells.
• If a new name is missing, save the notebook, check the generated metadata, and reload the add-in. Restart or reload the managed kernel after code changes.
• Function help pages are generated under help/functions/<function ID>.html. Existing pages are preserved for manual editing; the generated metadata links Excel’s “Help on this function” to them.

Explore the other interface

Read the ribbon_function guide →

Client setup · Source and server setup