---
title: About the Python SDK
description: >-
  Run ShopifyQL queries from Python. Use the shopifyql package to query a store
  from a notebook or script and work with the results as pandas or polars
  DataFrames.
source_url:
  html: 'https://shopify.dev/docs/apps/build/shopifyql/python-sdk'
  md: 'https://shopify.dev/docs/apps/build/shopifyql/python-sdk.md'
---

# About the Python SDK

The ShopifyQL Python SDK runs a query from a notebook or a script. It returns the results as a pandas or polars DataFrame, ready for analysis, joins, and export. Use it when you want to analyze or export a store's commerce data instead of building an app UI. To build reporting into an app, use the [GraphQL Admin API](https://shopify.dev/docs/apps/build/shopifyql/graphql-admin-api) instead, which returns structured `tableData` for you to render in your app's UI.

***

## How it works

The `shopifyql` package wraps the GraphQL Admin API so you work in Python instead of raw GraphQL. It authenticates as a Shopify app, so it needs your store's subdomain and an access token for an app installed on that store. How you get that token depends on where you run the SDK:

* In a Shopify CLI notebook, the `from_oauth` helper completes the OAuth flow and gets the token for you.
* In your own app, you pass the offline access token the app already holds. For how apps obtain and store it, refer to [Offline access tokens](https://shopify.dev/docs/apps/build/authentication-authorization/access-tokens/offline-access-tokens).

You create a client, then call a query method with a ShopifyQL string, where [`FROM` and `SHOW`](https://shopify.dev/docs/api/shopifyql/latest/syntax/from-and-show) name the dataset and the metrics to return. Each method returns the same data in a different shape:

* `client.query()` returns records.
* `client.query_pandas()` returns a pandas DataFrame.
* `client.query_polars()` returns a polars DataFrame.

## Python

```python
from shopifyql import ShopifyQLClient


client = ShopifyQLClient.from_oauth(shop="your-store")


df = client.query_pandas(
    "FROM sales SHOW total_sales, orders TIMESERIES day SINCE -7d ORDER BY day ASC"
)
```

**Info:**

Running a query needs the `read_reports` access scope and [Level 2 access to protected customer data](https://shopify.dev/docs/apps/launch/protected-customer-data).

***

## Developer tools and resources

[ShopifyQL Python SDK on GitHub\
\
](https://github.com/Shopify/shopifyql-py)

[The `shopifyql` Python library, with pandas and polars integration.](https://github.com/Shopify/shopifyql-py)

[ShopifyQL reference\
\
](https://shopify.dev/docs/api/shopifyql)

[Browse every dataset, metric, and dimension.](https://shopify.dev/docs/api/shopifyql)

***

## Get started

[Run a query with the Python SDK\
\
](https://shopify.dev/docs/apps/build/shopifyql/python-sdk/run-a-query)

[Scaffold a notebook with the Shopify CLI, run a query, and work with the results as a pandas DataFrame.](https://shopify.dev/docs/apps/build/shopifyql/python-sdk/run-a-query)

***