getting-started.md

jupyter

jupytext kernelspec language_info plotly notebook_metadata_filter text_representation all extension format_name format_version jupytext_version .md markdown 1.1 1.1.1 display_name language name Python 3 python python3 codemirror_mode file_extension mimetype name nbconvert_exporter pygments_lexer version name version ipython 3 .py text/x-python python python ipython3 3.7.3 description has_thumbnail language layout name page_type permalink redirect_from Getting Started with Plotly for Python. false python base Getting Started with Plotly u-guide python/getting-started/ python/getting_started/ /python/pytables/

Overview

The plotly Python library (plotly.py) is an interactive, open-source plotting library that supports over 40 unique chart types covering a wide range of statistical, financial, geographic, scientific, and 3-dimensional use-cases.

Built on top of the Plotly JavaScript library (plotly.js), plotly.py enables Python users to create beautiful interactive web-based visualizations that can be displayed in Jupyter notebooks, saved to standalone HTML files, or served as part of pure Python-built web applications using Dash.

Thanks to deep integration with the orca image export utility, plotly.py also provides great support for non-web contexts including desktop editors (e.g. QtConsole, Spyder, PyCharm) and static document publishing (e.g. exporting notebooks to PDF with high-quality vector images).

Installation

plotly.py may be installed using pip...

$ pip install plotly==4.8.1

or conda.

$ conda install -c plotly plotly=4.8.1

This package contains everything you need to write figures to standalone HTML files.

Note: No internet connection, account, or payment is required to use plotly.py. Prior to version 4, this library could operate in either an "online" or "offline" mode. The documentation tended to emphasize the online mode, where graphs get published to the Chart Studio web service. In version 4, all "online" functionality was removed from the plotly package and is now available as the separate, optional, chart-studio package (See below). plotly.py version 4 is "offline" only, and does not include any functionality for uploading figures or data to cloud services.

import plotly.graph_objects as go
fig = go.Figure(data=go.Bar(y=[2, 3, 1]))
fig.write_html('first_figure.html', auto_open=True)

Jupyter Notebook Support

For use in the classic Jupyter Notebook, install the notebook and ipywidgets packages using pip...

$ pip install "notebook>=5.3" "ipywidgets>=7.2"

or conda.

$ conda install "notebook>=5.3" "ipywidgets>=7.2"

These packages contain everything you need to run a Jupyter notebook...

$ jupyter notebook

and display plotly figures inline using the notebook renderer...

import plotly.graph_objects as go
fig = go.Figure(data=go.Bar(y=[2, 3, 1]))
fig.show()

or using FigureWidget objects.

import plotly.graph_objects as go
fig = go.FigureWidget(data=go.Bar(y=[2, 3, 1]))
fig

See Displaying Figures in Python for more information on the renderers framework, and see Plotly FigureWidget Overview for more information on using FigureWidget.

JupyterLab Support (Python 3.5+)

For use in JupyterLab, install the jupyterlab and ipywidgets packages using pip...

$ pip install jupyterlab "ipywidgets>=7.5"

or conda.

$ conda install jupyterlab "ipywidgets=7.5"

Then run the following commands to install the required JupyterLab extensions (note that this will require node to be installed):

# JupyterLab renderer support
jupyter labextension install jupyterlab-plotly@4.8.1

# OPTIONAL: Jupyter widgets extension
jupyter labextension install @jupyter-widgets/jupyterlab-manager plotlywidget@4.8.1

These packages contain everything you need to run JupyterLab...

$ jupyter lab

and display plotly figures inline using the plotly_mimetype renderer...

import plotly.graph_objects as go
fig = go.Figure(data=go.Bar(y=[2, 3, 1]))
fig.show()

or using FigureWidget objects (if the "OPTIONAL" step above was executed).

import plotly.graph_objects as go
fig = go.FigureWidget(data=go.Bar(y=[2, 3, 1]))
fig

Please check out our Troubleshooting guide if you run into any problems with JupyterLab.

See Displaying Figures in Python for more information on the renderers framework, and see Plotly FigureWidget Overview for more information on using FigureWidget.

Static Image Export Support

plotly.py supports static image export using the to_image and write_image functions in the plotly.io package. This functionality requires the installation of the plotly orca command line utility and the psutil and requests Python packages.

Note: The requests library is used to communicate between the Python process and a local orca server process, it is not used to communicate with any external services.

These dependencies can all be installed using conda:

$ conda install -c plotly plotly-orca==1.2.1 psutil requests

Or, psutil and requests can be installed using pip...

$ pip install psutil requests

and orca can be installed according to the instructions in the orca README.

These packages contain everything you need to save figures as static images.

import plotly.graph_objects as go
fig = go.FigureWidget(data=go.Bar(y=[2, 3, 1]))
fig.write_image('figure.png')

See Static Image Export in Python for more information on static image export.

Extended Geo Support

Some plotly.py features rely on fairly large geographic shape files. The county choropleth figure factory is one such example. These shape files are distributed as a separate plotly-geo package. This package can be installed using pip...

$ pip install plotly-geo==1.0.0

or conda.

$ conda install -c plotly plotly-geo=1.0.0

See USA County Choropleth Maps in Python for more information on the county choropleth figure factory.

Chart Studio Support

The chart-studio package can be used to upload plotly figures to Plotly's Chart Studio Cloud or On-Prem services. This package can be installed using pip...

$ pip install chart-studio==1.0.0

or conda.

$ conda install -c plotly chart-studio=1.0.0

Note: This package is optional, and if it is not installed it is not possible for figures to be uploaded to the Chart Studio cloud service.

Where to next?

Now that you have everything installed, you are ready to start reading and running examples of basic charts, statistical charts, scientific charts, financial charts, geographic charts and maps, and 3-dimensional charts.

For a complete overview of all of the ways that figures can be created and updated, see the Plotly User Guide for Python.

For information on configuring figure layout options (e.g. axes, titles, legends, etc) and styling figures (e.g. colors, fonts, annotations, images, shapes, etc.), see Plotly Fundamentals.

For information on theming plotly figures, see Theming and templates with plotly for Python.

For information on all of the ways that plotly figures can be displayed, see Displaying plotly figures with plotly for Python.

For the full searchable reference of every figure property, see the Python figure reference.

For information on using Python to build web applications containing plotly figures, see the Dash User Guide.