PyStackQL - Python Wrapper for StackQL

StackQL is an open source developer tool which allows you to query and interact with cloud and SaaS provider APIs using SQL grammar. StackQL can be used for cloud inventory analysis, cloud cost optimization, cloud security and compliance, provisioning/IaC, assurance, XOps, and more.

PyStackQL is a Python wrapper for StackQL which allows you to use StackQL within Python applications and to use the power of Python to extend StackQL. PyStackQL can be used with pandas, matplotlib, plotly, jupyter and other Python libraries to create powerful data analysis and visualization applications.

For detailed documentation, including the API reference, see Read the Docs.

Installing PyStackQL

PyStackQL can be installed with pip as follows:

pip install pystackql

You can install from source by cloning this repository and running a pip install command in the root directory of the repository:

git clone https://github.com/stackql/pystackql
cd pystackql
pip install .

Using PyStackQL

The following example demonstrates how to run a query and return the results as a pandas.DataFrame:

from pystackql import StackQL
region = "ap-southeast-2"
stackql = StackQL(output='pandas')

query = """
SELECT instance_type, COUNT(*) as num_instances
FROM aws.ec2.instances
WHERE region = '%s'
GROUP BY instance_type
""" % (region)

df = stackql.execute(query)
print(df)

Using PyStackQL with Jupyter Notebook

To use the integrated Jupyter magic commands provided by PyStackQL:

Load the Extension:

%load_ext pystackql.magic

Execute a Query Using Line Magic:

%stackql SHOW SERVICES IN azure

Or Using Cell Magic:

%%stackql
SELECT status, count(*) as num_instances
FROM google.compute.instances
WHERE project = '$project'
AND zone = '$zone'
GROUP BY status

You can find more examples in the stackql docs or the examples in readthedocs.

Supported Operating Systems

PyStackQL (and StackQL) are supported on:

MacOS (arm and amd)
Linux
Windows

Supported Python Versions

PyStackQL has been tested on:

Python 3.9
Python 3.10
Python 3.11
Python 3.12
Python 3.13

Licensing

PyStackQL is licensed under the MIT License. The license is available here

Building the docs

To build the docs, you will need to install the following packages:

pip install sphinx sphinx_rtd_theme sphinx-autodoc-typehints

Then, from the root directory of the repository, run:

cd docs
make html

The docs will be built in the docs/build/html directory.

Building the package

To build the package, you will need to install the following packages:

pip install build twine

Then, from the root directory of the repository, run:

rm -rf dist/*
python3 -m build

The package will be built in the dist directory.

Testing Locally

Before testing, ensure you have all the required packages installed:

pip install -r requirements.txt
pip install psycopg

Once the dependencies are installed, you can run the tests using the provided script:

sh run_tests

This script sets up the necessary environment variables and then runs the unit tests.

Note: Make sure to set up the environment variables in the tests/creds/env_vars/test.env file or supply them in another way before running the tests. The tests may require specific configurations or access keys to connect to services.

For better isolation and reproducibility, consider using a virtual environment:

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Once you’re done testing, you can deactivate the virtual environment:

deactivate

Publishing the package

To publish the package to PyPI, run the following command:

twine upload --config-file .pypirc dist/*

Release files for pystackql 3.8.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pystackql 3.8.4
File	Size	Uploaded
pystackql-3.8.4.tar.gz	47.8 kB	Jun 29, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for pystackql 3.8.4
File	Interpreter	ABI	Platform	Reset
pystackql-3.8.4-py3-none-any.whl 34.6 kB Jun 29, 2026	Python 3	none	any	Details

Total release size: 82.4 kB

Release files / pystackql-3.8.4.tar.gz

Download URL	pystackql-3.8.4.tar.gz
Size	47.8 kB
Tags	Source
SHA-256 checksum How to use checksums	`f408980b42512f9fc3c46e949d89293eac9cb2e715851db1ada77ae290891dff`
BLAKE2b-256 checksum How to use checksums	`8c3cb5d3b24d2dfcb48f78d2231134302d53ed2e946296ed8e6c04190b0c35ad`
Upload date	Jun 29, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.12.3`

Release files / pystackql-3.8.4-py3-none-any.whl

Download URL	pystackql-3.8.4-py3-none-any.whl
Size	34.6 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`192d32378b2dbfbcce010af749fece9762c0e2a8ab9f342a16f567e8caac8e1b`
BLAKE2b-256 checksum How to use checksums	`574affc0404fbc2c2e333ec115a0ffb05d71b215505e201ccc5cc687610b5764`
Upload date	Jun 29, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.12.3`