Show Sidebar Hide Sidebar

Getting Started with Plotly for Matplotlib

Plotly's Matplotlib graphing library makes interactive, publication-quality graphs online. Examples of how to make line plots, scatter plots, area charts, bar charts, error bars, box plots, histograms, heatmaps, subplots, multiple-axes, polar charts and bubble charts.

Getting started with Plotly for Matplotlib


To install Plotly's Python package, use the package manager pip inside your terminal.

$ pip install plotly


$ sudo pip install plotly

If you don't have pip installed on your machine, click here for pip's installation instructions.

Plotly's Python package is updated frequently! To upgrade, run:

$ pip install plotly --upgrade


Plotly for Python can be configured to render locally inside Jupyter (IPython) notebooks, locally inside your web browser, or remotely in your online Plotly account.
Remote hosting on Plotly is free for public use. For private use, view our paid plans.

Offline Use

Standalone HTML

Offline mode will save an HTML file locally and open it inside your web browser.

import plotly
print(plotly.__version__)  # version >1.9.4 required
from plotly.graph_objs import Scatter, Layout
"data": [
    Scatter(x=[1, 2, 3, 4], y=[4, 1, 3, 7])
"layout": Layout(
    title="hello world"
Learn more by calling help:

import plotly

Inside Jupyter/IPython Notebooks

import plotly
print(plotly.__version__)           # version 1.9.4 required
plotly.offline.init_notebook_mode() # run at the start of every notebook
"data": [{
    "x": [1, 2, 3],
    "y": [4, 2, 5]
"layout": {
    "title": "hello world"

Learn more about offline mode

Hosting on Plotly

Plotly provides a web-service for hosting graphs. Create a free account to get started. Graphs are saved inside your online Plotly account and you control the privacy. Public hosting is free, for private hosting, check out our paid plans.

In the terminal, copy and paste the following to install the Plotly library and set your user credentials.

$ pip install plotly
$ python -c "import plotly;'DemoAccount', api_key='lr1c37zw81')"

You'll need to replace 'DemoAccount' and 'lr1c37zw81' with your Plotly username and API key.

Find my API key.

To host your graph in your plotly account:

import plotly.plotly as py      # Every function in this module will communicate with an external plotly server
py.plot({                      # use `py.iplot` inside the ipython notebook
"data": [{
    "x": [1, 2, 3],
    "y": [4, 2, 5]
"layout": {
    "title": "hello world"
}, filename='hello world',      # name of the file as saved in your plotly account
sharing='public')            # 'public' | 'private' | 'secret': Learn more:

Special Instructions for Plotly On-Premise users

Your API key for account on the public cloud will be different than the API key in Plotly On-Premise. Visit to find your Plotly On-Premise API key. Remember to replace "" with the URL of your Plotly On-Premise server.

If your company has a Plotly On-Premise server, change the Python Open Source Graphing Library endpoint so that it points to your company's Plotly server instead of Plotly's cloud.

In your Terminal, enter:

$ python -c "import plotly;'',
plotly_streaming_domain='', plotly_api_domain='')"

Make sure to replace "" with the URL of your Plotly On-Premise server. Questions? Email

Start plotting!

Make a graph using Matplotlib syntax:

import matplotlib.pyplot as plt
import plotly.plotly as py

mpl_fig = plt.figure()
# --> your matplotlib methods <--

unique_url = py.plot_mpl(mpl_fig, filename="plotly version of an mpl figure")

Alternatively, convert matplotlib figures into Plotly figure objects with mpl_to_plotly:

import matplotlib.pyplot as plt
import as tls

mpl_fig = plt.figure()
# --> your matplotlib methods <--

plotly_fig = tls.mpl_to_plotly(mpl_fig)

unique_url = py.plot(plotly_fig)

You can also create plotly graphs with our native Python syntax. Learn more in our python documentation.


The initialization step places a special .plotly/.credentials file in your home directory. Your ~/.plotly/.credentials file should look something like this:

    "username": "DemoAccount",
    "stream_ids": ["ylosqsyet5", "h2ct8btk1s", "oxz4fm883b"],
    "api_key": "lr1c37zw81"

You can change the contents of this file manually or as described in the Initialization section.