Update install instructions in First Steps

Just a suggestion about the install instructions in the First Steps guide. The guide is excellent, but when trying to follow it I ran into a difference between Bokeh version 3.0.1 and the Anaconda version 2.4.3. I spent too many hours this morning trying different update approaches from support sites like Stack Overflow to no avail. That is, until I put two separate suggestions together to create a new environment after adding the bokeh channel and making that channel the priority. Without doing that, Anaconda appears to fail to update the default environment bokeh package past 2.4.3.

So my suggestion is to update the First Steps guide to walk through this process:

  1. Add the bokeh channel
  2. Set channel priority to strict
  3. Edit the channel config file to reorder the channels to place bokeh on top
  4. Create a new environment
  5. Activate the new environment
  6. Add the bokeh package to the environment

Then conda appears to install bokeh version 3.0.1.

Hi @907sjl thank you for sharing your experience and the suggestion. Personally, however, I think I am not inclined to make those changes. Major releases like 3.0 are very rare (there have only been three in ~12 years!) So I would hate to take very simple instructions that will work 99% of the time, and make them substantially more complicated just for the 1% of time when when things are still settling after a major release. (AFAIK Bokeh 3.0.1 will be available on Anaconda defaults very soon, but ultimately we do not control their schedule.)

cc @Timo for thoughts

@907sjl Actually don’t the instructions already state that, more or less?

Make sure you have either Anaconda or Miniconda installed. Use this command to install Bokeh:

conda install bokeh

Alternatively, if you want to make sure you always have the most recent version of Bokeh after each new release, install from the Bokeh channel directly:

conda install -c bokeh bokeh

I’m looking here: Installation details — Bokeh 3.0.1 Documentation

is there some other page you are referring to that doesn’t mention using -c bokeh to get the latest version? Or are you saying conda install -c bokeh was not sufficient? If so, I think there is something specific going on with your envs, since that has always been sufficient AFAICT.

@timo FYI I would consider revising this:

The easiest way to install Bokeh is to use conda . Conda is part of the Anaconda Python Distribution, which is designed with scientific and data analysis applications like Bokeh in mind.

I think we can be more neutral here, and even start positioning pip install instructions first, since the only “standard” package repository publish we completely control and can guarantee will be available immediately, is PyPI (and also since it is generally fine to pip install Bokeh into conda envs).

Edit: issue made to discuss this change: More neutral install instructions · Issue #12595 · bokeh/bokeh · GitHub

Unfortunately, no. I did the due diligence and tried that but the default Anaconda environment remained stubbornly linked to bokeh version 2.4.3. Only the steps that I outlined allowed the update to resolve an install sequence for version 3.0.1. Mind you, I just installed Anaconda on this computer today.

@907sjl I’m not sure what to tell you, the second version definitely grabs the latest version for me:

base ❯ conda install -c bokeh bokeh
Collecting package metadata (current_repodata.json): done
Solving environment: done

## Package Plan ##

  environment location: /Users/bryan/anaconda

  added / updated specs:
    - bokeh


The following packages will be downloaded:

    package                    |            build
    ---------------------------|-----------------
    contourpy-1.0.5            |   py38haf03e11_0         191 KB
    xyzservices-2022.9.0       |   py38hecd8cb5_0          42 KB
    ------------------------------------------------------------
                                           Total:         234 KB

The following NEW packages will be INSTALLED:

  contourpy          pkgs/main/osx-64::contourpy-1.0.5-py38haf03e11_0 None
  xyzservices        pkgs/main/osx-64::xyzservices-2022.9.0-py38hecd8cb5_0 None

The following packages will be UPDATED:

  bokeh              pkgs/main/osx-64::bokeh-2.4.2-py38hec~ --> bokeh/noarch::bokeh-3.0.1-py_0 None
  ca-certificates                     2022.07.19-hecd8cb5_0 --> 2022.10.11-hecd8cb5_0 None
  openssl                                 1.1.1q-hca72f7f_0 --> 1.1.1s-hca72f7f_0 None

Regardless, we are actually going to move the pip instrucions first, since the new releases are always immediately available on PyPI, and since pip installing Bokeh into a conda env is generally fine.