Tapir / Tutorials / First Python script

Your first Archicad Python script.

A Tapir script is a Python file that sends JSON commands to Archicad. This one asks Archicad how many elements are selected, and runs from the Tapir palette.

Install Tapir

Install the Tapir Add-On with the Tapir Installer, as Get started shows, and start Archicad with a project open. The Tapir palette runs scripts with uv, which brings the Python each script needs; if uv is not installed yet, Tapir offers to install it the first time you run a script.
2
Make a folder with aclib

Make a folder for your scripts, for example Documents/Tapir scripts, and an aclib folder inside it. Download builtin-scripts/aclib/__init__.py into that aclib folder. aclib is the small helper of the built-in scripts: it sends a Tapir command to Archicad and returns the answer.
Documents/Tapir scriptsfolder
```
FirstScript.py
aclib/
    __init__.py
```

Write the script

Save this as FirstScript.py in the folder. The two headers are those of the built-in scripts, described in builtin-scripts/README.md: uv reads the first, and the palette shows changes as Read only. The last two lines are archicad-addon/Examples/Element/GetSelectedElements.py, the example of GetSelectedElements.

FirstScript.pyPython

# /// script
# requires-python = ">=3.11"
# dependencies = []
# ///

# /// tapir
# changes = "read-only"
# ///

"""
First Script

Prints how many elements are selected in Archicad.
"""
import aclib

selectedElements = aclib.RunTapirCommand ('GetSelectedElements', {})['elements']
print ('{} elements are selected.'.format (len (selectedElements)))

Run it from the palette

Add the folder to localFolders in Documents/Tapir/config.json, with the displayName My scripts, as Get started shows. Choose Tapir Palette from the Tapir menu, then Reload scripts... at the bottom of its script list.

Select a few elements in Archicad, pick FirstScript (My scripts) in the palette's list and click Run Script. The palette reports what the script prints, such as 3 elements are selected. Edits to the file take effect the next time you run it.

The palette starts the script with uv run --script FirstScript.py --port <port>, and aclib reads --port, so the script talks to the Archicad whose palette started it. With Python installed, you can also run it yourself as python FirstScript.py; it then uses the first Archicad, on port 19723.
5
Call another command

Every Tapir command is called the same way: its name and a dictionary of its parameters. These lines count the walls of the project with GetElementsByType:
FirstScript.pyPython
```
walls = aclib.RunTapirCommand ('GetElementsByType', {'elementType': 'Wall'})['elements']
print ('{} walls in the project.'.format (len (walls)))
```
The command reference lists every command with its parameters, its response and an example like the one above. To send the commands without aclib, see Write a script of your own.