_ _ ___
| | | | / |
__ _ _ __ ___| |_| |/ /| |_ __ _ _
/ _` | '__/ _ \ __| / /_| | '_ \| | | |
| (_| | | | __/ |_| \___ | |_) | |_| |
\__, |_| \___|\__|_| |_/ .__/ \__, |
__/ | | | __/ |
|___/ |_| |___/
gretl4py provides Python bindings for gretl, giving Python programs direct access to libgretl, the numerical and econometric engine underlying gretl.
gretl4py brings gretl's econometric, statistical, numerical, and data-management functionality into Python while providing Python-oriented interfaces for datasets, matrices, models, bundles, function packages, and other gretl objects.
gretl4py is not a separate reimplementation of gretl in Python. Estimation and many numerical operations are performed directly by libgretl, while Python provides the programming environment and access to the wider scientific-computing ecosystem.
gretl4py provides, among other things:
Current releases support Python 3.11, 3.12, 3.13, and 3.14. Pre-built packages are available for the supported operating systems and architectures.
For normal use, installation of a pre-built package is recommended. gretl4py is distributed via PyPI.
On GNU/Linux:
python3 -m pip install gretl4py
On macOS:
python3 -m pip install --user gretl4py
On MS Windows:
python.exe -m pip install gretl4py
Pre-built gretl4py packages are also available through Conda:
conda install -c marcin_gretlconference.org gretl4py
Pre-built development snapshots are available from the gretl4py snapshots area. Download the wheel matching your Python version, operating system, and architecture and install it using pip.
On GNU/Linux or macOS:
python3 -c "import gretl; gretl.about(True)"
On MS Windows:
python.exe -c "import gretl; gretl.about(True)"
A typical gretl4py workflow consists of loading a dataset, specifying a model, fitting it using libgretl, and working with the resulting Python object:
import gretl
data = gretl.get_data("denmark.gdt")
model = gretl.ols(
["LRM", "const", "LRY", "IBO"],
data=data
).fit()
print(model)
Estimator functions return model objects; estimation is performed by calling .fit(). Model specifications can use variable names, variable numbers, or gretl-style specifications where supported.
For example:
model = gretl.ols([1, 0, 2, 3], data=data).fit()
or:
model = gretl.ols("LRM const LRY IBO", data=data).fit()
The Python API is organized around several classes that correspond closely to native libgretl objects.
gretl4py is designed to work naturally with the Python scientific-computing ecosystem.
For example, a gretl matrix can be exposed directly as a NumPy view:
m = gretl.Matrix.ones(3, 3) a = m.to_numpy() # independent NumPy array v = m.numpy_view # writable zero-copy view
A gretl dataset can be converted to a pandas DataFrame:
df = data.to_pandas()
This makes it possible to use libgretl for econometric estimation while using NumPy, pandas, matplotlib, and other Python libraries for subsequent processing and visualization.
gretl4py provides direct access to the gretl function-package ecosystem. Functions implemented in hansl packages can therefore be called from Python without being reimplemented as separate Python extensions.
For example:
import gretl
gretl.pkg("install", "BMA")
BMA = gretl.include("BMA")
data = gretl.get_data("FLS_41t72.gdt", frompkg="BMA")
opt = gretl.Bundle()
opt["Nrep"] = 10**5
opt["model_prior"] = "binomial"
opt["Nrank"] = 5
result = gretl.BMA(
Y="GDP_growth",
X_list=list(range(2, 14)),
quiet=True,
Options=opt
)
gretl.BMA_Print(result)
In this example, BMA() and BMA_Print() are supplied by the gretl function package rather than being native gretl4py bindings.
The gretl4py distribution contains a growing collection of examples. Small examples of individual estimators are available under:
gretl/examples/estimators/
Examples demonstrating gretl function packages are available under:
gretl/examples/packages/
More extensive demonstrations are available under:
demo/
These cover data handling, matrices, bundles, estimation, model diagnostics, forecasting, VAR/VECM functionality, filters, nonlinear models, function packages, hansl interoperability, and other gretl4py features.
For normal use, the pre-built packages described above are recommended. Source builds use the Meson build system and Ninja and require a suitable libgretl development environment and a C++17 compiler.
On MS Windows (x86-64 and ARM64), native builds use the Microsoft Windows SDK, LLVM/Clang, and the libgretl for MS SDK stack. MSVC cannot currently be used to build gretl4py because of an ABI incompatibility involving the representation of complex numbers.
The libgretl for MS SDK stack contains the libraries required for compiling and linking gretl4py against libgretl. Additional libraries required at run time by individual gretl plugins must be supplied separately where needed.
Complete and current build instructions for GNU/Linux, macOS, MS Windows x86-64, and MS Windows ARM64 are given in the gretl4py documentation.
The gretl4py PDF documentation provides the complete API reference, installation and compilation instructions, and numerous usage examples.
Project resources:
Example data and scripts from Principles of Econometrics, 4th edition, are available at Principles_of_Econometrics_4th_edition.zip .
Marcin Błażejowski, marcin(at)gretlconference(dot)org
Last updated: 2026-10-06