These are the most important concepts and terms that you will encounter
throughout Bokeh’s documentation:
Visual aids that make reading the plot easier. This includes titles,
legends, labels, or bands, for example. See Adding annotations
in the User guide for more information and examples.
A Bokeh application is a recipe for generating Bokeh
documents. Typically, this is Python code run by a
Bokeh server whenever a new sessions is created.
handles the UI interactions for Bokeh plots and
widgets in the browser. In most cases, Bokeh handles all
don’t have to”). For more details, see the BokehJS
chapter of the developers guide.
An organizing data structure for Bokeh
applications. Documents contain all the Bokeh
models and data needed to render an interactive
visualization or application in the browser.
Various methods that help with including Bokeh plots and
widgets in web apps, web pages, or Jupyter notebooks.
See Embedding Bokeh content in the User guide for more details.
API objects that draw vectorized graphics to represent data. Glyphs are
the basic visual building blocks of Bokeh plots. This
includes elements such as lines, rectangles, squares, wedges, or the
circles of a scatter plot. The The bokeh.plotting interface
interface provides a convenient way to create plots centered around
glyphs. See Plotting with basic glyphs in the User guide for more
A collection of Bokeh objects. This can be several plots
and widgets, arranged in nested rows and columns. See
Creating layouts in the User guide for more information and
The lowest-level objects that Bokeh visualizations consist of. Bokeh’s
models are part of the The bokeh.models interface interface.
Most users will not use this level of interface to assemble plots
directly. However, ultimately all Bokeh plots consist of collections of
models. It is helpful to understand them enough to configure their
attributes and properties. See Styling visual attributes in the
User guide for more information.
Containers that hold all the various objects (such as
renderers, glyphs, or
annotations) of a visualization. The
The bokeh.plotting interface interface provides the
figure() function to help with assembling all the
General term for any method or function that draws elements of the plot.
Examples of elements that are generated by renderers are
glyphs or annotations.
The Bokeh server is an optional component. You can use the Bokeh server
to share and publish Bokeh plots and apps, to handle streaming of large
data sets, or to enable complex user interactions based on
widgets and selections. See Running a Bokeh server in
the User guide for more information and examples.
User interface elements that are not directly part of a Bokeh
plot, such as sliders, drop-down menus, or buttons. You
can use events and data from widgets in your Python code, or you can
use input from widgets to update you Bokeh plot itself. You can use
widgets in standalone applications or with the
Bokeh server. For examples and information, see
Making Interactions in the User guide.
Bokeh offers a variety of ways to produce interactive output. The following
two functions are the most common:
Generate simple standalone HTML documents for Bokeh visualizations.
Display Bokeh visualizations in Jupyter/Zeppelin notebooks.
These output functions are usually used together with show()
or save(). Here’s an example:
from bokeh.plotting import figure, output_file, show
p = figure()
p.line(x=[1, 2, 3], y=[4,6,2])
This script generates an HTML file called output.html that contains a line
plot. You can execute it with python foo.py, where foo.py is the name
of the script.
These functions are often useful in interactive settings or for creating
standalone Bokeh documents to serve from backend web applications.
Another way to generate various kinds of output is by using Bokeh’s powerful
command line tool.
Bokeh provides a simple and intuitive interface for users like data scientists
and domain experts who do not wish to be distracted by complex details of the
software. At the same time, Bokeh also caters to people such as application
developers and software engineers who may want more control or access to more
Because of this, Bokeh takes a layered approach and offers different programming
interfaces appropriate to different users.
This section provides an overview of the two interfaces that you can use: the
primary interface bokeh.plotting and
the low-level bokeh.models interface.
If you’d prefer to jump right into basic plotting, go to
Plotting with basic glyphs. For a simple step-by-step guide to creating
visualizations with Bokeh, see the first steps guides.
bokeh.plotting is Bokeh’s primary interface. This general-purpose
interface is similar to plotting interfaces of libraries such as Matplotlib
The bokeh.plotting interface lets you focus on relating glyphs to data. It
automatically assembles plots with default elements such as axes, grids, and
tools for you.
The figure() function is at the core of the bokeh.plotting interface. This
function creates a Figure model that includes methods for adding different
kinds of glyphs to a plot. This function also takes care of composing the
various elements of your visualization, such as axes, grids, and tools.
Below is an example of bokeh.plotting, along with the resulting
from bokeh.plotting import figure, output_file, show
# create a Figure object
p = figure(plot_width=300, plot_height=300, tools="pan,reset,save")
# add a Circle renderer to this figure
p.circle([1, 2.5, 3, 2], [2, 3, 1, 1.5], radius=0.3, alpha=0.5)
# specify how to output the plot(s)
# display the figure
Calling the figure() function is all it takes to create a basic plot object. To
add data renderers to your plot object, call a glyph method such as
Figure.circle. You don’t have to worry about axes and grids (although you can
configure them if you want to), and you only need to list the tools you want to
add. To display your visualization in a browser, in most cases, all you need to
do is call the output function show().
With the bokeh.plotting interface, you have many more possibilities to
create an customize your visualization. For example:
saving the plot to an HTML file instead of showing it
styling and removing axes, grids, annotations, and interactive elements
adding more data renderers
arranging multiple plots and widgets into layouts
The Plotting with basic glyphs section of this User guide will walk you
through many more examples and common use cases for the bokeh.plotting
For an easy to follow guide to building your first visualizations with Bokeh,
see the first steps guides.
With Bokeh’s low-level bokeh.models interface, you have complete control
over how Bokeh creates all elements of your visualization. However, Bokeh’s
low-level interface doesn’t help you assemble the various elements in meaningful
or correct ways. It is entirely up to you to put them together.
Therefore, unless you have special applications that require finer control,
you will probably want to use the bokeh.plotting interface
To be able to use the bokeh.models interface, you need to understand the
basic principle by which Bokeh enables you to generate interactive,
browser-based visualizations. Behind the scenes, Bokeh consists of two
BokehJS runs in the browser. This library handles rendering and user
interactions. It takes a collection of declarative JSON objects as its input
and uses them as instructions on how to handle the various aspects of your
visualization in a browser. For example:
plots and widgets
layouts and arrangements
tools and renderers
In the browser, BokehJS converts these JSON objects into BokehJS models and
renders them according to corresponding BokehJS views.
The Python library generates the JSON objects that BokehJS uses to render
your visualization in a browser.
At its lowest level, the Python library uses a set of model classes that
exactly mirror the set of models that BokehJS creates in a browser.
These Python model classes are able to validate their content and
attributes and serialize themselves to JSON. Most of the models are very
simple and usually consist of only a few property attributes and no methods.
You can configure the attributes of those models either by setting them when
creating a model or later by setting attribute values on the model object.
You can access all low-level model objects through Bokeh’s bokeh.models
For example, to create and configure a Rect glyph object:
# configure attributes when initializing a model object
glyph = Rect(x="x", y="y2", w=10, h=20, line_color=None)
# assign values to attributes to an existing model object
glyph.fill_alpha = 0.5
glyph.fill_color = "navy"
You can generally configure all Bokeh models this way. Since all Bokeh
interfaces ultimately produce collections of Bokeh models, this lets you
style and configure plots and widgets the same way regardless of the
For more information on Bokeh models, consult the Reference.
The Python library allows for binding with other languages that can produce
appropriate JSON output. For more details and available bindings, see