Checking for non-preferred file/folder path names (may take a long time depending on the number of files/folders) ...

Creating a Conda Environment for Future-Proofing Jupyter Notebooks to Support Computational Reproducibility
Authors:
Owners: This resource does not have an owner who is an active HydroShare user. Contact CUAHSI (help@cuahsi.org) for information on this resource.
Type: Resource
Storage: The size of this resource is 1.9 MB
Created: Feb 10, 2026 at 7:58 p.m. (UTC)
Last updated: Mar 26, 2026 at 6:41 p.m. (UTC)
Citation: See how to cite this resource
Sharing Status: Public
Views: 210
Downloads: 262
+1 Votes: Be the first one to 
 this.
Comments: No comments (yet)

Abstract

Computational reproducibility requires that a Jupyter notebook produce consistent results regardless of where it is executed—whether on a local machine, within JupyterHub environments such as CIROH-2i2c and CUAHSI JupyterHub, or on another platform. In practice, notebooks developed in one environment may fail in another environment due to differences in Python versions, missing or incompatible packages, or environment-specific permission constraints. Even minor version mismatches can sometimes cause code to break or generate inconsistent outputs. In general a best practice is to only rely on stable, widely compatible libraries and simpler methods. Jupyter notebook developers should have future reproducibility in mind and code in ways that do not rely on capabilities that may go out of date where possible. However, even with this defensive coding there are library compatibility situations that are impossible to avoid when considering the future proofing of a Jupyter notebook.

This resource present methods for future-proofing of Jupyter notebooks through the use of custom Conda environments to defining and preserving a controlled software environment that can be recreated more reliably over time. It describes how to use a custom Conda environment that explicitly captures required dependencies, increasing the reliability of consistent execution across computing environments.

This HydroShare resource provides a structured, notebook-driven workflow for creating and managing such a custom Conda environment for notebooks launched through HydroShare’s “Open With” JupyterHub environments. The core notebook, CondaEnvironmentSetup.ipynb, guides users through defining the environment name and specifying dependencies in an accompanying environment.yml file. It then invokes supporting Bash scripts to automate Conda environment creation, Jupyter kernel registration, and optional cleanup.

Subject Keywords

Content

readme.md

Creating a Conda Environment for Future-Proofing Jupyter Notebooks to Support Computational Reproducibility

This HydroShare resource provides a reproducible, notebook-driven workflow for creating and managing a custom Conda environment. The goal of this resource is to help users future-proof their notebooks by capturing required dependencies in a Conda environment that can be recreated and reused consistently.

This resource is configured for use with JupyterHub platforms such as CUAHSI and CIROH-2i2c JupyterHub linked to HydroShare. To see how this resource works, use HydroShare's "Open With" to open it on one of these platforms. Once in the platform, work through the CondaEnvironmentSetup.ipynb notebook as described below.

📁 Resource Contents

This resource includes the following files:

  • CondaEnvironmentSetup.ipynb
    The main notebook users should follow. It provides step-by-step instructions for creating, registering, and managing a custom Conda environment as a Jupyter kernel.

  • environment.yml
    Defines the Python packages and versions required for the Conda environment. This file should be updated by users to match their environment requirements.

  • setup_jupyterhub_conda_env.sh
    A shell script invoked by the notebook to create the Conda environment from environment.yml and register it as a Jupyter kernel. Users do not need to edit this script directly.

  • delete_jupyterhub_conda_env.sh
    A shell script invoked by the notebook to remove an existing Conda environment and its associated Jupyter kernel when needed. Users do not need to edit this script directly.

  • Example
    A folder containing a shapefile of the Great Salt Lake Basin used in an example demonstrating why a custom Conda environment is required.

  • readme.md
    This file, which describes the content of this resource.

🚀 How to Use This Resource

  1. Launch this resource in a HydroShare-supported JupyterHub environment using Open With.
  2. Open the CondaEnvironmentSetup.ipynb notebook.
  3. Define or update the required inputs:
    • Conda environment name: Specify the desired name of the Conda environment in CondaEnvironmentSetup.ipynb.
    • Environment specification (environment.yml): Edit this file to include the Python packages and versions required for the environment to be created.
  4. Follow the instructions on the CondaEnvironmentSetup.ipynb notebook to create and register the environment as a Jupyter kernel.
  5. Switch your notebook kernel to the newly created environment and begin working.

If dependency requirements change, update environment.yml and rerun the setup steps to recreate the environment.

💡 Notes

  • This resource is designed for Jupyter notebooks launched through HydroShare’s JupyterHub environments and assumes standard Conda and Bash support provided by those platforms.
  • Users should list all required dependencies in environment.yml rather than installing packages interactively within notebooks.
  • When switching kernels, the newly created Conda environment may not appear immediately; restarting the kernel can refresh the available kernel list.

👥 Intended Audience

This resource is intended for researchers, students, and practitioners who share and run Jupyter notebooks within HydroShare and want to improve reproducibility and long-term usability of their computational workflows.

📧 Contact

For questions or suggestions, please contact:

Credits

Funding Agencies

This resource was created using funding from the following sources:
Agency Name Award Title Award Number
National Oceanic and Atmospheric Administration (NOAA), University of Alabama CIROH: Enabling collaboration through data and model sharing with CUAHSI HydroShare NA22NWS4320003 to University of Alabama, subaward A23-0266-S001 to Utah State University
National Science Foundation HDR Institute: Geospatial Understanding through an Integrative Discovery Environment 2118329

How to Cite

Salehabadi, H., D. Tarboton, P. Dash (2026). Creating a Conda Environment for Future-Proofing Jupyter Notebooks to Support Computational Reproducibility, HydroShare, http://www.hydroshare.org/resource/1c5fd6dd6b0c4fb4b5f65cce35550a38

This resource is shared under the Creative Commons Attribution CC BY.

 http://creativecommons.org/licenses/by/4.0/
CC-BY

Comments

There are currently no comments

New Comment

required