Setting up a development environment#
The Bokeh project consists of two major components: the Bokeh package source code, written in Python, and the BokehJS client-side library, written in TypeScript.
Therefore, you need to set up two environments to contribute to Bokeh: A Python environment and a TypeScript environment. This chapter walks you through all the necessary steps to set up a full development environment.
1. Check basic requirements#
Install or update Git#
The Bokeh source code is stored in a Git source control repository. The first step to working on Bokeh is to install or update Git on your system.
If you have never used Git before, you can find links to several beginner tutorials and resources in the Git documentation.
Install or update conda#
To be able to manage Python and non-Python dependencies in one place, Bokeh uses
the conda package manager.
conda is part of the free Anaconda Python
distribution available for Windows, macOS, and Linux. Conda creates and manages
virtual environments for you. Therefore, you don’t need tools like
pipenv. While it is technically possible to install all
dependencies manually without
conda, this guide will assume that you have
conda is already installed on your system, make sure it is up to date
by running the following command:
conda update -n base -c defaults conda
2. Fork and clone the repository#
Cloning the repository creates a
bokeh directory at your file system
location. This local
bokeh directory is referred to as the source checkout
for the remainder of this document.
3. Create a conda environment#
The Bokeh repository you just cloned to your local hard drive contains an
environment.yml file. In this file is all the necessary
information to automatically create a basic development environment. The name of
this virtual environment will be
conda env create at the root level of your source checkout directory
to set up the environment and install all necessary packages:
conda env create -f environment.yml
Then, activate the environment:
conda activate bkdev
To update your local environment, use
conda env update -f environment.yml. Updating your local environment
is necessary whenever the dependencies in
environment.yml change. This
can happen when the environment file is updated in the main Bokeh repository
or when you switch branches to work on different issues, for example.
4. Install Node packages#
the Node Package Manager (npm). If you have followed the
conda has already installed the necessary
packages to your system.
Bokeh usually requires the latest major revision of
npm. To install the
newest version globally, start from the top level of the source checkout
directory, and run the following commands:
cd bokehjs npm install -g npm@8
If you do not want to install npm globally, leave out the
-g flag. In this
case, you need to adjust all subsequent
npm commands to use the local
version installed under
Next, still in the
bokehjs subdirectory, run the following command
This command installs the necessary packages into the
Typically, you only need to do this once when you first set up your local environment. However, if dependencies are added or changed, you need to repeat these steps to install and update the respective packages.
5. Set up pre-commit#
Bokeh uses pre-commit to help you prevent some common mistakes in your commits.
To set up pre-commit locally, run the following command from the top level of your source checkout directory:
This configures pre-commit to use two Git hooks that will check your code whenever you push a commit to Bokeh’s GitHub repository:
- Codebase tests
- Protected branches
git-commit will make sure you don’t accidentally push a commit to Bokeh’s protected branches
Depending on your system, running those tests may take several dozen seconds. If any of the tests fail, check the output of your console. In most cases, this is where you will find the necessary information about what you need to change to pass the tests.
To uninstall the Git hooks, run the following command from the top level of your source checkout directory:
6. Build and install locally#
Once you have all the required dependencies installed, the simplest way to
build and install Bokeh and BokehJS is to use the
setup.py script. This
script is located at the top level of the source checkout directory.
setup.py script has two main modes of operation:
python setup.py develop
Bokeh will be installed to refer to your local source directory. Any changes you make to the Python source code will be available immediately without any additional steps. This is the recommended mode when working on the Bokeh codebase.
python setup.py install
Bokeh will be installed in your local Python
site-packagesdirectory. In this mode, any changes to the Python source code will have no effect until you run
Running either of those two commands also builds and installs a local version of
BokehJS. If you want to skip building a new version of BokehJS and use a
different local version instead, use the
python setup.py develop --install-js
You need to rebuild BokehJS each time the BokehJS source code changes.
This can be necessary because you made changes yourself or because you
pulled updated code from GitHub. Re-run
python setup.py develop to build
and install BokehJS.
In case you update from a development environment based on Bokeh 2.3 or
older, you most likely also need to delete the
bokehjs/build folder in
your local environment before building and installing a fresh BokehJS.
7. Download sample data#
Several tests and examples require Bokeh’s sample data to be available on your hard drive. After installing Bokeh, use the following command to download and install the data:
You also have the opportunity to configure the download location or to start the download programmatically. See the Installing sample data section of the first steps guides for more details.
8. Set environment variables#
Bokeh uses environment variables to control several aspects of how the different parts of the library operate and interact.
To learn about all environment variables available in Bokeh, see bokeh.settings in the reference guide.
When working on Bokeh’s codebase, the most important environment variable to be
aware of is
BOKEH_RESOURCES. This variable controls which version of
BokehJS to use.
You have the following three options to use your local version of BokehJS:
$Env:BOKEH_RESOURCES = "absolute-dev"
$Env:BOKEH_RESOURCES = "inline"
server-devto load your local BokehJS through a Bokeh server.
First, start a local server.
BOKEH_DEV=true bokeh static
$Env:BOKEH_DEV = "true" bokeh.exe static
set BOKEH_DEV=true bokeh static
Next, open a new terminal window and set
$Env:BOKEH_RESOURCES = "server-dev"
Resources for more details.
There are several other environment variables that are helpful when working on
Bokeh’s codebase. The most common settings for local development are combined in
To enable development settings, set
$Env:BOKEH_DEV = "true"
true is equivalent to setting all of the following
This way, Bokeh will use local and unminified BokehJS resources, the default log
levels are increased, the generated HTML and JSON code will be more
human-readable, and Bokeh will not open a new browser window each time
9. Test your local setup#
Run the following tests to check that everything is installed and set up correctly:
Test Bokeh core#
First, use the following command to test the Bokeh installation:
python -m bokeh info
You should see output similar to:
Python version : 3.9.7 | packaged by conda-forge | (default, Sep 29 2021, 19:20:46) IPython version : 7.20.0 Tornado version : 6.1 Bokeh version : 3.0.0dev1+20.g6c394d579 BokehJS static path : /opt/anaconda/envs/test/lib/python3.9/site-packages/bokeh/server/static node.js version : v16.12.0 npm version : 7.24.2 Operating system : Linux-5.11.0-40-generic-x86_64-with-glibc2.31
Next, run some of the standalone examples included with Bokeh.
Make sure the environment variable
BOKEH_RESOURCES is set to
inline in order to use
your local version of BokehJS. In the source checkout directory, run the
BOKEH_RESOURCES=inline python examples/plotting/file/marker_map.py
$Env:BOKEH_RESOURCES = "inline" python.exe .\examples\plotting\file\marker_map.py
set BOKEH_RESOURCES=inline python examples\plotting\file\marker_map.py
This creates a file
marker_map.html locally. When you open this file in a web
browser, it should display this visualization:
Run Bokeh Server#
BOKEH_DEV=false python -m bokeh serve --show examples/app/sliders.py
$Env:BOKEH_DEV = "False" python.exe -m bokeh serve --show .\examples\app\sliders.py
set BOKEH_DEV=false python -m bokeh serve --show examples\app\sliders.py
This should open up a browser with an interactive figure:
All the sliders allow interactive control of the sine wave, with each update
redrawing the line with the new parameters. The
--show option opens a
web browser. The default URL for the Bokeh server is
If you keep getting errors after updating an older environment, use
conda remove --name bkdev --all, delete your local
and reinstall your development environment, following the steps in this guide
from the beginning.