qgrid - SlickGrid in Jupyter Notebooks

Qgrid is an IPython widget which uses a javascript library called SlickGrid to render pandas DataFrames within a Jupyter notebook. It was developed for use in Quantopian's hosted research environment.


  • SlickGrid is a javascript grid which allows users to scroll, sort, and filter hundreds of thousands of rows with extreme responsiveness.
  • Pandas is a powerful data analysis / manipulation library for Python, and DataFrames are the primary way of storing and manipulating two-dimensional data in pandas.

Qgrid renders pandas DataFrames as SlickGrids, which enables users to explore the entire contents of a DataFrame using intuitive sorting and filtering controls. It's designed to be used within Jupyter notebook, and it's also mostly functional when rendered by nbviewer.

Notebook installation

First, import the qgrid module as you would any other module in Python. If that doesn't work, something may have gone wrong while installing the qgrid package using pip. I would go through the package installation steps on the GitHub page again with a new virtualenv to make sure everything installed correctly.

In [ ]:
import qgrid
Prepare non-python dependencies by calling nbinstall

This step is required because at this point all you've done to install qgrid is to call pip install. Pip doesn't know which folder your Jupyter notebook widgets need to get copied to (let's call this the "widgets folder"), only the Jupyter notebook process knows that. So you need to run one line of code from within the Jupyter notebook to copy qgrid to the widgets folder. This only has to be done once for a particular version of qgrid. That being said, if you're running qgrid from it's source code and making changes to it's source code, you'll need to run this line every time you make a change, or else the changes won't do anything. See our API docs for the nbinstall function for more details.

In [ ]:
qgrid.nbinstall(overwrite=True)  # copies javascript dependencies to your /nbextensions folder

API & Usage

API documentation is hosted on readthedocs: http://qgrid.readthedocs.org/en/latest/

The API documentation can also be accessed via the "?" operator in IPython. To use the "?" operator, type the name of the function followed by "?" to see the documentation for that function, like this:


Example 1 - Render a DataFrame returned by Yahoo Finance

1. Create a sample DataFrame using the get_data_yahoo function and render it without using qgrid

In [ ]:
import pandas as pd
import numpy as np
randn = np.random.randn

# Set this pandas option to prevent the grid from being too big
pd.set_option('display.max_rows', 8)

# Get a pandas DataFrame containing the daily prices for the S&P 500 from 1/1/2011 - 1/1/2014
from pandas_datareader.data import get_data_yahoo
spy = get_data_yahoo(

The table above is Jupyter notebook's default representation of the 'spy' DataFrame.

2. Render the DataFrame again, this time using qgrid

In [ ]:

The cell above shows the same 'spy' DataFrame rendered as a qgrid. Qgrids allows you to scroll, sort, and filter hundreds of thousands of rows with extreme responsiveness. If you double click on the cells they become editable, and the edits change the values stored in the DataFrame as you would expect.

3. Now render with qgrid again, and set the grid_options parameter

The show_grid function takes a number of optional parameters to allow you to configure the behavior of the grid it generates. In the following example we use the grid_options parameter.

grid_options takes a dict and allows you to pass any of the "grid options" listed in SlickGrid's documentation. In this example we make use of two of these options, forceFitColumns and defaultColumnWidth, to improve qgrid's ability to handle a large number of columns. You can read about grid_options and the rest of the optional parameters for the show_grid function in our API documentation.

If you find yourself frequently passing the same options into show_grid, the set_defaults function may be useful to you. It allows you to set the same options that you would normally pass to show_grid, but through a separate function which sets the options for the lifetime of the kernel rather than for a single grid. See the API documentation for the set_defaults function for more information.

In [ ]:
qgrid.show_grid(spy, grid_options={'forceFitColumns': False, 'defaultColumnWidth': 200})

The same 'spy' DataFrame rendered as a qgrid again, this time some options tweaked. The toolbar buttons are visible, the columns are wider, and a horizontal scroll bar has appeared.

Example 2 - Render a DataFrame returned by World Bank's World Development Indicators

1. Create a sample DataFrame using the wb.download function and render it without using qgrid

In [ ]:
from pandas_datareader import wb
df2 = wb.download(indicator='NY.GDP.PCAP.KD', country=['all'], start=2005, end=2008)
df2.columns = ['GDP per capita (constant 2005 US$)']

2. Render the DataFrame again, this time using qgrid

In [ ]:

Example 3 - Rendering a grid by creating a QGridWidget

1. Create a new sample DataFrame and render it without using qgrid

In [ ]:
df3 = pd.DataFrame({
    'A' : 1.,
    'B' : pd.Timestamp('20130102'),
    'C' : pd.Series(randn(8),index=list(range(8)),dtype='float32'),
    'D' : np.array([3] * 8,dtype='int32'),
    'E' : pd.Categorical(["washington", "adams", "madison", "lincoln","jefferson", "hamilton", "roosevelt", "kennedy"]),
    'F' : 'foo' })

2. Render the DataFrame again, this time using the QGridWidget class directly

The show_grid function is just a convenience function which internally constructs an instance of QGridWidget and renders it with jupyter notebook's display function. The following code shows how to construct a QGridWidget directly, so that you can retrieve or update the DataFrame it uses internally.

In [ ]:
from IPython.display import display
grid = qgrid.QGridWidget(df=df3)

3. Get the DataFrame back from the QGridWidget and render it without qgrid

If you make edits to the data using the grid above, they will be reflected in the DataFrame that is returned by grid.df.

In [ ]: