Skip to content

Write a custom CodeCheck (Python)

Custom checks let you enforce team-specific rules. Write them in Python (.upy).

Perl (.upl) is deprecated

Perl CodeCheck scripts still run, but the Perl API is deprecated as of 2026 and will be removed. Write new checks in Python.

Anatomy of a .upy check

A check is a Python file defining these functions:

def ids():                      # unique CheckID(s), e.g. ("MYTEAM_01",)
def name(id):                   # display name (supports "Folder/Name")
def tags(id):                   # categorization tags
def description(id):            # short description
def detailed_description(id):   # full explanation shown in the GUI
def test_language(language):    # return True for languages this check applies to
def test_entity(file):          # True if it runs per-file/entity
def test_global():              # True if it runs once for the whole project
def define_options(check):      # e.g. check.option().integer(...) / .checkbox(...)
def check(check, file):         # the actual logic

Report a violation

Inside check(...), call check.violation(...):

check.violation(ent, file, line, column, "message %1", arg1)

(ent is the entity the violation is on; file, line, column locate it; the message may take positional args.)

Install and run it

Drop the .upy file into your per-user CodeCheck plugin directory:

OS Directory
Windows C:\Users\<you>\AppData\Roaming\SciTools\plugin\Codecheck
Linux ~/.config/SciTools/plugin/Codecheck
macOS ~/Library/Application Support/SciTools/plugin/Codecheck

Then, in Understand, open Tools → Plugin Manager and click Rescan Plugins (the ↻ button — discards cached plugin info and reloads from disk) so your new check appears. Select it in a CodeCheck configuration and Inspect.

Learn the API