Skip to content


Repository files navigation


CircleCI PyPI ReadTheDocs Coverage Status

PyBloqs is a flexible framework for visualizing data and automated creation of reports.

pybloqs in use in ipython notebook


It works with Pandas, matplotlib and highcharts. PyBloqs creates atomic blocks containing text, tables (from Pandas DataFrame), plots (matplotlib or highcharts) or images. All blocks can be styled with CSS. Each block can be created and displayed separately for fast development turnover. Lists of blocks can be stacked together to form reports. Reports can be displayed as HTML in the browser or exported in a variety of formats (including HTML, PDF, SVG, PNG).


Install PyBloqs

For a minimal install without HighCharts support run:

pip install pybloqs

or when installing in development mode:

python develop

This will allow you to run the example code below.

External dependencies

For full functionality, PyBloqs requires the following 3rd party programs and libraries. For some, the file location must be specified at install time:

pip install --install-option="INSTALL OPTIONS" git+


pip install --install-option="--highcharts=~/node_modules/highcharts/,~/node_modules/highcharts-heatmap/" git+

wkhtmltopdf is not bundled with PyBloqs. You need to install it from your distribution's repository (Linux) or download it from the project page ( . The binaries wkhtmltopdf and wkhtmltoimage are used for file output other than HTML. PyBloqs will search for the binaries on the system path. If you would like to use a local copy of the binaries, install with following option:


When installing in development mode you can load wkhtmltopdf explicitly:

python load_wkhtmltopdf --wkhtmltopdf=/path/to/binary
  • Node.js with comander and puppeteer (optional; for PDF output with 'chrome_headless' backend). Please make sure these are available globally. In development mode, you can run
npm install

in the main PyBloqs directory.

  • Bokeh (optional). To install Bokeh dependency, you can use:
pip install pybloqs[bokeh]
  • Plotly (optional). To install Plotly dependency, you can use:
pip install pybloqs[plotly]

Highcharts is not bundled with PyBloqs. To create blocks with Highcharts plots, you need to download Highcharts separately (e.g. with npm install highcharts, npm install highcharts-heatmap etc.), and provide the path to your highcharts installation. Please make sure you have the right license for Highcharts. For full functionality you will need the following highcharts packages: highcharts, highcharts-heatmap, highcharts-funnel, highcharts-exporting, highcharts-export-csv (this example assumes, npm installed files into directory ~/node_modules).


When installing in development mode you can load highcharts explicitly (this example assumes, npm installed files into directory ~/node_modules)

python load_highcharts --highcharts=~/node_modules/highcharts/,~/node_modules/highcharts-heatmap/,\

Using PyBloqs

from pybloqs import Block, HStack, VStack
import pandas as pd
from matplotlib import pyplot as plt

text_block = Block('This is a text block', styles={'text-align':'center', 'color':'blue'})

df = pd.DataFrame([[1., 2.],[3.,4.]], columns =['a', 'b'])
table_block = Block(df)

plot_block = Block(plt.plot(df['a'], df['b']))

plot_and_table = HStack([plot_block, table_block])
report = VStack([text_block, plot_and_table])'report.pdf')


You can specify per-user default parameters in a yaml-formatted file ~/.pybloqs.cfg. This config file allows you to setup a call setup and login sequence against an smtplib.SMTP ( object. The following works for Google gmail - more details here (

  port: 587
- !!python/tuple
  - ehlo
  - {}
- !!python/tuple
  - starttls
  - {}
- !!python/tuple
  - ehlo
  - {}
  password: a_secret
public_dir: /tmp
tmp_html_dir: /tmp


Have a look at the detailed documentation.


PyBloqs works with:

  • matplotlib
  • Pandas
  • html5lib
  • lxml
  • jinja2
  • markdown
  • beautifulsoup4
  • docutils


PyBloqs has been under active development at Man AHL since 2013.

Original concept and implementation: Tom Farnbauer


Contributions welcome!


PyBloqs is licensed under the GNU LGPL v2.1. A copy of which is included in LICENSE