Quick Start¶

This quick start guide sets up a local development environment.

1. Get a License Key¶

Get a trial license key as you will need it in the next step.

2. Install xlwings-server¶

Install uv, Python’s modern package manager. Run the following commands on a Terminal:

Windows

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

macOS and Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

Create a new uv project (I’ll be calling it myproject here) and change into the directory:
```
uv init myproject
cd myproject
```
Install xlwings-server and watchfiles (for hot-reloading), then initialize xlwings-server:
```
uv add xlwings-server
uv add watchfiles --dev
uv run xlwings-server init .
```
Add the license key to the .env file:
```
XLWINGS_LICENSE_KEY="your-license-key"
```
Create SSL/TLS certificates for local development:

Excel requires the server to run on HTTPS (not HTTP), even for local development. Download mkcert (pick the correct file according to your platform), rename the file to mkcert, then run the following commands from a Terminal/Command Prompt (make sure you’re in the same directory as mkcert):
```
./mkcert -install
./mkcert localhost 127.0.0.1 ::1
```
This will generate two files localhost+2.pem and localhost+2-key.pem. Move them to the certs directory of your project. Note that mkcert is only for local development, not for production deployments!

Run the server

uv run xlwings-server

You should see output along the following lines:

INFO:     Will watch for changes in these directories: ['/Users/felix/dev/myproject']
INFO:     Uvicorn running on https://127.0.0.1:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [77403] using WatchFiles
INFO:xlwings_server.main:Running in 'Server' mode.
INFO:     Started server process [77411]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

3. Install the Excel add-in¶

With the server running, go to https://127.0.0.1:8000/manifest/download in a browser. This downloads the Office.js manifest as <project-name>-dev.xml. The manifest is an XML file that you load into Excel and that points Excel to your backend server. During development, sideload the manifest according to your platform:

In Excel, go to Add-ins on the ribbon’s Home tab:

Windows: click on More Add-ins > Shared Folder. Select the add-in, then click on Add.
macOS: you will see your add-in listed under Developer add-ins. Note that you will have to activate the add-in every time you restart Excel.

4. Take it for a Spin!¶

Now you are ready to play around with the provided examples:

Scripts: custom_scripts/scripts.py -> click the button in the task pane (see templates/taskpane.html). See Custom Scripts for more information.
Custom Functions: custom_functions/functions.py -> write the following formula into Excel =XLWINGS_DEV.HELLO("xlwings"). See Custom Functions for more information.

5. Set up Version Control¶

Once you have a working development environment, you should commit everything to Git.