Run Python in Calc Through LibreOffice’s Macro System

If a Python script runs from your terminal but cannot read or change the spreadsheet open in Calc, it is probably running outside LibreOffice. A Calc Python macro needs to run inside the LibreOffice process, where LibreOffice supplies the active document context. Save the script as a module in your user Python scripts folder, export its function with g_exportedScripts, and launch it from Calc’s macro dialog.

This is the simplest path for a small automation tied to the open workbook. LibreOffice’s current Python scripting help describes both in-process macros and separately connected Python scripts; the steps below use the in-process method.

Why doesn’t a regular Python script see the open spreadsheet?

LibreOffice exposes the current document to a running Python macro through the global XSCRIPTCONTEXT. A script launched with your regular python command is a separate process, so that global is not automatically available. It can still communicate with LibreOffice, but that requires setting up a UNO connection to an already running office process. For a first macro, run the function inside LibreOffice instead.

A Python macro is a function in a .py module. The module’s g_exportedScripts tuple tells LibreOffice which functions to show in its macro list. These details are documented in LibreOffice’s Python programming reference.

How do you add a Python macro to Calc?

1. Find the user Python scripts folder

Use the personal My Macros location if you want a script that can run from any open LibreOffice document for your user account. LibreOffice documents the folder as %APPDATA%\LibreOffice\4\user\Scripts\python on Windows and $HOME/.config/libreoffice/4/user/Scripts/python on Linux and macOS. If the Scripts/python folders do not exist yet, create them. The script locations reference also explains the other macro containers: Application Macros and macros embedded in a document.

Document macros are stored inside a particular file and are only accessible while that document is open. For a reusable personal utility, My Macros is usually easier to maintain. Avoid modifying LibreOffice’s application-wide macro folder, which may require administrator access.

2. Create and export a small test function

Open a plain-text editor, create hello_calc.py in the folder above, and add:

def hello_calc(*args):
    doc = XSCRIPTCONTEXT.getDocument()
    sheet = doc.Sheets[0]
    sheet.getCellRangeByName("A1").setString("Hello from Python")

g_exportedScripts = (hello_calc,)

The function gets the document currently connected to the macro call, selects its first sheet, and writes a harmless test string in A1. The final line is important: without the exported tuple, the function may not appear as a runnable macro. Save the file as plain text with the .py extension, not as a rich-text document or a file ending in .py.txt.

LibreOffice supplies XSCRIPTCONTEXT to the macro module. It does not automatically pass that variable to modules imported by your code, so keep the first test self-contained. If you later split reusable functions into other modules, follow LibreOffice’s Python module import guidance.

3. Open a Calc file and run the exported function

1. Open a test spreadsheet in Calc. Use a copy or a blank workbook while developing.
2. Choose Tools > Macros > Run Macro.
3. In the library list, expand My Macros, choose the Python module, and select hello_calc from the macro names.
4. Click Run.

The same function can be started from the APSO extension, which LibreOffice recommends for in-process Python scripting and also provides a Python shell. You do not need APSO for the basic Run Macro flow described here.

What if the macro is missing or appears to do nothing?

Work through these checks in order rather than changing broad security settings:

• The module is not listed: confirm the file is in the exact user Scripts/python path, has a .py suffix, and contains a correctly spelled g_exportedScripts tuple. Reopen the macro dialog; if LibreOffice still does not list a newly added file, close and restart LibreOffice, then check again.
• The macro name is missing: make sure the exported tuple includes the function object, for example (hello_calc,). The comma makes this a one-item Python tuple.
• Nothing appears in the terminal: output from print() is not available when Python macros run from the standard macro dialog. The test above writes into A1 so the result is visible in the sheet. For interactive debugging, APSO’s shell displays output.
• An import fails: installing a package for your system Python does not guarantee that LibreOffice’s Python runtime can import it. The package must be available on the runtime’s Python path; the official import guidance describes user and shared module paths. Start by testing the macro without optional imports.
• A security warning appears: only run scripts you wrote or have reviewed and trust. Macro security exists to limit unsafe code; do not lower the global security level just to make an unfamiliar document’s macro run. Consult LibreOffice’s macro security options if you need to understand a warning.

Choose the external-process approach only when your automation must start from a terminal, scheduler, or another application. LibreOffice requires you to start the office process with a pipe or socket and connect through its UNO bridge; an ordinary standalone script is not equivalent to an in-process Calc macro.

How can you verify that the macro worked?

After clicking Run, look at cell A1 on the first sheet. It should contain Hello from Python, and the formula bar should show the same text when A1 is selected. If the cell remains unchanged, confirm that the intended workbook was active and that the macro was selected from My Macros. Once this minimal test succeeds, replace the test write with your real calculation and test it on a copy of the workbook before using it on important data.