_   _   ___
               | | | | /   |
  __ _ _ __ ___| |_| |/ /| |_ __  _   _
 / _` | '__/ _ \ __| / /_| | '_ \| | | |
| (_| | | |  __/ |_| \___  | |_) | |_| |
 \__, |_|  \___|\__|_|   |_/ .__/ \__, |
  __/ |                    | |     __/ |
 |___/                     |_|    |___/

gretl4py is a python package designed to meet the needs of econometricians and applied economists who wish to use python in their research. It can be broadly viewed as a complement to the statsmodels package, with a more specific orientation to the inference methods commonly employed in applied economics.

gretl4py provides an interface to libgretl for the Python language (3.11, 3.12, and 3.13 were tested). Libgretl is the underlying engine for the gretl program. At present, the focus is mostly on the APIs implementing estimation methods, but a larger array of facilities is planned.

gretl4py consists of the following elements:

• binary bindings written in C++,
• a Model class implemented in Python,
• a set of utility functions implemented in Python.

Preparation

• One of the supported versions of Python (3.11, 3.12 or 3.13).
• The Python packages numpy and (optionally) tabulate.
• On macOS: gretl version 2024c or higher; see this page.
• On Linux: also gretl 2024c or higher, either from a binary package (Debian/Ubuntu/Fedora) or self-compiled.
• On MS Windows: gretl version 2025a or higher (snapshots may be downloaded from here).

Download and install

You can download gretl4py as a zip archive from here. Unzip the archive (preserving its directory structure). The top-level directory is called gretl4py, and inside it you'll find a Python script named install.py. Just execute this script as follows:

• MS Windows: python.exe install.py
• macOS or Linux: python3 install.py

We can't guarantee that the pre-compiled binary module installed by install.py will work on all Linux systems. But on Linux you have the alternative of building gretl4py yourself; see below.

The install.py script copies the following files to the user's site-packages directory:

• __init__.py, gretl4py_addons.py, and gretl4py_classes.py from the gretl subdirectory.
• _gretl.cp3xx-win_amd64.pyd (for MS Windows) or _gretl.cpython-3xx-darwin.so (for macOS) from the builds/3.xx subdirectory.

Here, 3.xx refers to the version of Python used to run install.py. To see exactly where the files were installed, you can execute the following:

• MS Windows: python.exe showdir.py
• macOS or Linux: python3 showdir.py

If there are no errors in copying the required files, install.py checks that the gretl4py module can be loaded, and calls the function gretl.about(). If all goes well this will give text output on

• your gretl4py build;
• your system, according to gretl's $sysinfo accessor;
• a few libgretl built-in strings; and
• the simdjson architecture.

Building on Linux

You can find instructions in section 2.3 of the gretl4py documentation. Besides a C++ compiler with support for c++17 standard, you'll need these development packages associated with gretl 2024c or higher:

• Debian/Ubuntu: libgretl1-dev, python3-dev
• Fedora: gretl-devel, python3-devel

Running gretl4py

You can find a good number of sample *.py files in the demo and examples subdirectories of gretl4py. The contents of these files can be examined in any suitable text editor. Starting from the gretl4py directory, one way of getting a sense of what this package can do is:

cd demo
python3 estimators.py

(Substitute python.exe for python3 on Windows.) You can also run gretl4py interactively. Start the python executable and type the command import gretl. Then besides any regular python commands you can call any of the functions described in the gretl4py documentation.

Documentation

The pdf documentation contains many more details about the gretl4py module, including a listing of the available APIs and several usage examples.

Marcin Błażejowski, marcin(at)gretlconference(dot)org

Last updated: 2025-03-23