Using Highcharts Gantt for Python: Basic Tutorial

Highcharts Gantt is a powerful JavaScript data visualization library that enables you to design rich, beautiful, and highly interactive Gantt charts, providing instant insight into your project progress, critical paths, and roadmaps. Using Highcharts Gantt for Python, which is part of the broader Highcharts for Python Toolkit, you can easily and rapidly use Highcharts Gantt in your Python code.

Building off of the Highcharts Stock for Python library which already provides over 100 different base visualizations, Highcharts Gantt and Highcharts Gantt for Python also give you the capability to construct rich Gantt visualizations, including:

Expandable task groupings
The visualization of completion percentages
Panning, scrolling, and zooming across a project’s overall timeline
Direct integration with major project management platforms including Asana, JIRA, and Monday.com.

Highcharts Gantt for Python will not render data visualizations itself – that’s what Highcharts Gantt (in JavaScript) does – but it will allow you to:

Configure your Gantt chart in Python.
Configure your Gantt chart’s style and interactivity in Python.
Supply data you have in Python (or in one of the most popular project management platforms) to your data visualizations.
Programmatically produce the Highcharts Gantt JavaScript code that will actually render your Gantt chart.
Programmatically download a static version of your Gantt chart (as needed) within Python.

Tip
Think of Highcharts Gantt for Python as a translator to bridge your Gantt charting needs between Python and JavaScript.

Getting Started with Highcharts Gantt for Python

To use Highcharts Gantt for Python, like with any Python library, you first have to install it. That’s super easy: just open your Python project (in your virtual environment – you are using virtual environments, right?) and execute:

$ pip install highcharts-gantt

And that’s it! Highcharts Gantt for Python will now be installed in your project and available for use. To use it in your code, you just have to import it the way you would any other library.

Tip
If you expect to use Highcharts Gantt for Python with project management platforms like Asana, Monday.com, or Atlassian JIRA, then you should also install the corresponding libraries that enable communication with their APIs. You can either install them individually, or you can also install all soft dependencies alongisde Highcharts Gantt, using:

$ pip install highcharts-gantt[soft]

or individually:

$ pip install asana
$ pip install monday
$ pip install jira

What’s Included in Highcharts Gantt for Python?

Highcharts Gantt for Python is specifically designed to provide rich Gantt chart visualization in your Python code. While the base Highcharts Stock for Python library is designed to provide rich interactive visualizations of time series data, Highcharts Gantt for Python goes further to provide you with:

Limitless Gantt Charting – but Batteries Included. While Highcharts Gantt for Python lets you easily build custom Gantt charts using project meta-data supplied by your Python application, you can also pull data from Pandas Dataframes or popular project management platforms like Asana, Monday.com, or Atlassian JIRA..
Rich Data Visualization. Highcharts Gantt supports multiple different types of Gantt visualizations, including standard Gantts and x-range visualizations.
Robust Navigation within and across Your Gantt Chart. Highcharts Gantt for Python provides you with the ability to let your users easily navigate across the full lifecycle of your project, using any combination of:
- Mouse and touch-enabled scrolling and panning,
- Mouse and touch-enabled zooming
- Plus or minus buttons that zoom you in or out, respectively
- Drilldown into specific sections or phases of your project
Highcharts Stock for Python. Highcharts Gantt for Python includes the complete Highcharts Stock for Python library, with the exact same API. This lets you import one library for all of your data visualization needs, whether working with Gantt data, other time series data, or any other kind of data.

Importing Highcharts Gantt for Python

The Highcharts Gantt for Python library is quite big. It’s got a rich (read: complicated) API, with lots of different objects and modules. That’s a reflection of the visualization power that Highcharts offers you, but it does make the decision of what to import and how to import it a little more complicated.
Python’s best practice is to import only what you need, which helps to maximize the performance of your Python code and prevents your application’s namespace from getting cluttered with various things (and further reducing the memory footprint of your Python code, which is always good).
You can either import specific things from their precise locations, or import the catch-all highcharts module, which flattens the entire API and exposes just about every class/object in one location. We definitely recommend importing things from their precise location like so:

# Import classes using precise module indications. For example:
from highcharts_gantt.chart import Chart
from highcharts_gantt.global_options.shared_options import SharedGanttOptions
from highcharts_gantt.options import HighchartsGanttOptions
from highcharts_gantt.options.plot_options.gantt import GanttOptions
from highcharts_gantt.options.series.ganttimport GanttSeries

As you can see, the import pattern for Highcharts Gantt for Python is very similar to other libraries in the Highcharts for Python toolkit. That is because Highcharts Gantt for Python is an extension of the Highcharts Stock for Python library, and it maintains the full API. Highcharts Gantt features are additive in relation to that API, so that you can import from one toolkit library throughout your application.
For example, if you wish to render a Gantt chart using Highcharts Gantt for Python, but also render a separate Sankey chart (available in Highcharts Core for Python), you can do both while using the Highcharts Gantt for Python library:

from highcharts_gantt.chart import Chart
from highcharts_gantt.global_options.shared_options import SharedGanttOptions
from highcharts_gantt.options import HighchartsGanttOptions
from highcharts_gantt.options.plot_options.gantt import GanttOptions
from highcharts_gantt.options.series.gantt import GanttSeries
from highcharts_gantt.options.plot_options.sankey import SankeyOptions
from highcharts_gantt.options.series.sankey import SankeySeries

A Super Simple Example

While your project is likely more complicated, let’s take a look at the easiest use case: visualizing some data quickly and easily. You likely have your data in a CSV file, or perhaps in a Pandas dataframe, or maybe just stored in a list in your Python code. Highcharts Gantt for Python can work with all of those scenarios.
When visualizing map data, the basic process is straightforward:

Creating Your Data Series

Using Highcharts Gantt for Python, you can configure your chart’s data visualizations exactly the same as you would using any library in the Highcharts for Python toolkit. In general, your data can either reside in a CSV file, a Pandas Dataframe, a PySpark Dataframe, or even a Python list instance.

Let’s assume we have a bunch of our task data in a Pandas DataFrame called df. We can create our GanttSeries or chart by calling .from_pandas() as shown below:

# Given a Pandas DataFrame instance named "df"
from highcharts_gantt.chart
import Chart
from highcharts_gantt.options.series.gantt
import GanttSeries
# Creating a Series from the DataFrame
my_series = GanttSeries.from_pandas(df,
  property_map = {
    'id': 'task_id',
    'name': 'summary',
    'start': 'start',
    'end': 'end',
    'dependency': 'depends_on',
    'completed': 'percent_complete'
  })
# Creating a Chart with a MapSeries from the GeoDataFrame.
my_chart = Chart.from_pandas(df,
  property_map = {
    'id': 'task_id',
    'name': 'summary',
    'start': 'start',
    'end': 'end',
    'dependency': 'depends_on',
    'completed': 'percent_complete'
  },
  series_type = 'gantt')

So what’s happening in the code above? In the first example, we’re creating a GanttSeries instance by calling the .from_pandas() class method on the GanttSeries class. We’re telling it to load the series data from the Pandas DataFrame instance called df, and we’re then providing it a property_map argument.
This property_map argument is “where the magic happens”, since it maps columns of data in your DataFrame to their corresponding properties in your GanttSeries .data property (which takes a GanttData instance).

In this case, we’re telling Highcharts Gantt for Python to populate each data point’s .id and .name properties (which give the data point a unique ID and specify the data point’s label, respectively) from the df column labeled “task_id” and “summary”, and to populate the .start and .end properties from the analogously labeled columns. Furthermore, we are telling it that it can identify dependencies between tasks by reading from the “depends_on” column in df, and it can find the percentage finished for the task in the “percent_complete” column.

Note
The .from_pandas() method is available on all series classes.

Other Approaches

The example above focuses on using a Pandas DataFrame, but Highcharts Gantt for Python has you covered regardless of how you are managing your data in your Python application. You have similar convenience functions for loading data:

.from_csv() which loads data from a CSV file.
.from_pyspark() which loads data from a PySpark Dataframe.
.from_asana() which loads data from a project in the Asana platform.
.from_monday() which loads data from a board in the Monday.com platform.
.from_jira() which loads data from a project in the Atlassian JIRA platform.

You can call these convenience methods on the Chart class as shown above, or you can also call the exact same convenience methods on a series type, and then add the series to a chart instance using the my_chart.add_series() method.

Tip
Our other tutorials show you in detail how to use these different convenience methods to rapidly build great visualizations – we recommend you check out here: Highcharts for Python Tutorials.

Visualizing Your Chart

Now that we’ve built a Chart instance and populated it with data, our next step is to visualize it. How you actually do this depends to some extent on how you are building your Python application.

Maybe you are using a web framework like Flask, Django, or FastAPI and relying on their templating engines for creating your views. Or maybe you are providing a Python backend API that delivers data to an entirely separate app via RESTful API calls. In any case, to visualize your new chart, you need to somehow get its configuration to your web-based front-end. And that is super simple as well.
Using the example above, you can generate the full set of HTML and JavaScript content to render your chart with one method call:

as_js_literal = my_chart.to_js_literal()
# This will produce a string similar to:
  #
# document.addEventListener('DOMContentLoaded', function() {
      #
      const myChart = Highcharts.chart('target_div', {
          # series: {
            # type: 'map',
            # data: [
              #['ny', 7],
              #['ma', 1],
              #['nj', 3]
              #
            }
            #
          }); #
      });

So what is this method call doing? It is taking the entire set of instructions included in your my_chart variable, creating a JavaScript literal string that represents them, and putting that string in the as_js_literal Python variable. This string can then be piped into your web front end using whatever templating engine you are using, or delivered to your front-end in an API response, and it will then render your chart as you configured it.

In the example above, if you place the as_js_literal string in what gets rendered in your user’s browser, your chart will be automatically rendered by Highcharts Gantt, placing the chart inside the div element in your content whose id is “target_div”.

And that’s it! You should now see a beautiful map chart in your web content.

Downloading Your Chart

Often when you’ve created a visualization, you may want to download a static version of it as an image that can be embedded in other documents. With Highcharts Gantt for Python, that is a fairly trivial exercise. Given the example above, you can produce a PNG image very simply with one method call:

# Download a PNG version of the chart in memory within your Python code.
my_png_image = my_chart.download_chart(format = 'png')
# Download a PNG version of the chart and save it the file "/images/my-chart-file.png"
my_png_image = my_chart.download_chart(
  format = 'png',
  filename = '/images/my-chart-file.png'
)

The two examples shown above both download a PNG of your chart:
The first example keeps that PNG image in your Python code only, storing its binary data in the my_png_image variable. The second example not only stores its binary data in the my_png_image variable, but it also saves the PNG image to the file “/images/my-chart-file.png”.

The format argument is really the one doing the heavy lifting above. The example above tells the method to generate a PNG image, but you can also create “jpeg”, “pdf”, and “svg”.

And that’s it! You should know that the .download_chart() method defaults to using the Highcharts Export Server provided by Highsoft (creators of Highcharts Core), however, you can configure the method to use your own custom Highcharts Export Server if you choose. For more details on how to do this, please review our tutorial on Exporting Static Charts using Highcharts for Python.

More Resources

The above tutorial is just a really simple example of how you can create rich visualizations with just a handful of method calls using Highcharts for Python. But the library offers so much more! We recommend you take a look at the following additional resources which you may find useful: