The following details how to install the
jdaviz Python package.
If you encounter problems while following these installation instructions, please consult known installation issues.
You may want to consider installing
jdaviz in a new virtual or conda environment
to avoid version conflicts with other packages you may have installed.
Some of Jdaviz’s dependencies require non-Python packages to work (particularly the front-end stack that is part of the Jupyter ecosystem). We recommend using Miniconda to easily manage a compatible Python environment for Jdaviz; it should work with most modern shells, except CSH/TCSH.
Once it is installed, we recommend you create a new environment rather than
installing everything into the
base environment, for example:
conda create -n jdaviz-env python=3.9 conda activate jdaviz-env
Installing the released version of Jdaviz can be done using
pip install jdaviz --upgrade
or if you want the latest development version, you can install via GitHub:
pip install git+https://github.com/spacetelescope/jdaviz --upgrade
jdaviz requires Python 3.8 or newer. If your
pip corresponds to an older version of
Python, it will raise an error that it cannot find a valid package.
Users occasionally encounter problems running the pure
pip install above. For those
conda, some problems may be resolved by pulling the following from
conda install bottleneck conda install -c conda-forge notebook conda install -c conda-forge jupyterlab conda install -c conda-forge voila
You might also want to enable the
ipywidgets notebook extension, as follows:
jupyter nbextension enable --py widgetsnbextension
If you wish to contribute to Jdaviz, please fork the project to your
own GitHub account. The following instructions assume your have forked
the project and have connected
your GitHub to SSH
username is your GitHub username. This is a one-setup setup:
git clone email@example.com:username/jdaviz.git cd jdaviz git remote add upstream firstname.lastname@example.org:spacetelescope/jdaviz.git git fetch upstream main git fetch upstream --tags
To work on a new feature or bug-fix, it is recommended that you build upon
the latest dev code in a new branch (e.g.,
You also need the up-to-date tags for proper software versioning:
git checkout -b my-new-feature git fetch upstream --tags git fetch upstream main git rebase upstream/main
For the rest of contributing workflow, it is very similar to
how to make code contribution to astropy,
except for the change log.
If your patch requires a change log, see
CHANGES.rst for examples.
jdaviz for development or from source in an editable mode
(i.e., changes to the locally checked out code would reflect in runtime
after you restarted the Python kernel):
pip install -e .
Optionally, to enable the hot reloading of Vue.js templates, install
pip install watchdog
watchdog, to use it, add the following to the top
of a notebook:
from jdaviz import enable_hot_reloading enable_hot_reloading()
See Quickstart to learn how to run