Environment configurations

Phase out notice

Nebari is evolving. The original Nebari project is now called Nebari Classic, and is in maintenance mode.

We'll continue to provide security updates and key bug fixes; however, no new features are planned at this time. We're using the lessons learned from Nebari Classic to build a new Nebari ecosystem of tools, on a more robust foundation with a modular architecture. Nebari Classic's maintenance window will remain open until the new architecture reaches stability and feature parity, and current users are able to migrate, expected through the end of 2026.

See the current Nebari documentation for details on the new platform.

Tip

For guidance on managing or creating environments directly with conda-store, see our guide on Creating new environments on Nebari. If you're looking for information on updating your namespaces after a recent upgrade, refer to our troubleshooting guide on Migrating namespaces.

Nebari comes with two default environments that are built during deployment:

• nebari-git-nebari-git-dask to run distributed workflows with Dask,
• nebari-git-nebari-git-dashboard to [create shareable dashboard][create-dashboards].

The configuration of each environment in Nebari is achieved through a environment.<filename> mapping to a conda environment specification. To configure environments, you can add entries to the nebari-config.yml file located in the deployment repository, which will then be used by conda-store to create or update the environment during deployment.

For example, the following snippet shows an environment configuration in nebari-config.yml:

### Example environment configuration
environments:
  "environment-example.yaml":
    name: example
    channels:
      - conda-forge
      - defaults
    dependencies:
      - python=3.9
      - ipykernel
      - ipywidgets
      - numpy
      - numba
      - pandas
      - jinja2
      - pyyaml

In this example, the environment is defined with the name "example" and includes various dependencies specified as a list of package names and versions. Additionally, two channels, conda-forge and defaults, are specified to be used to retrieve the packages during environment creation.

Note

One current requirement is that each environment must include ipykernel and ipywidgets to properly show up in the JupyterLab environment.

After you modify an environment definition in the configuration, it may take 1-10 minutes for the changes to take effect after you deploy the configuration. Once the environment is updated, you can access it from the JupyterLab environment selection menu under the nebari-git namespace. For example, if you created an environment called example (as show in the above example), it will be available as nebari-git-nebari-git-example.

Note

The double nebari-git is a known consequence of using conda-store for environment management.

Learn more in the FAQ: Why do I see duplication in the names of environments?

Caution

For versions of Nebari earlier than 2023.04.1, conda-store by default restricts the environment channels to only accept defaults and conda-forge.

Built-in namespaces:

In Nebari, namespaces are used to organize and isolate resources. Nebari has two built-in namespaces: nebari-git and global.

The nebari-git namespace refers to all available environments created using the nebari-config.yaml file and is available for all users and services. On the other hand, the global namespace (previously known as default) is the default namespace used by conda-store to manage its internal components and workers. It is designed for environments that are specific to a user or a service.

For more information, please refer to conda-store administration documentation related to CondaStore.default_namespace and CondaStore.filesystem_namespace respectively.

Note

By default, the namespace nebari-git is used in a standard Nebari deployment. However, you can change the namespace name by modifying the conda-store.default_namespace entry in your nebari-config.yaml configuration file. Keep in mind that this setting permanently changes the namespace name.

When you specify an environment in nebari-config.yml, it will be made available for all users and services under the nebari-git namespace. Conda-store is responsible for creating them upon request from the deployment process.

However, the conda-store permission model restricts user intervention for both namespaces. This means that nebari-git environments can only be modified within the Nebari deployments, while global environments can be locally changed via direct interaction with conda activate. However, any changes made to global environments will only be perceived by the user and not propagated to other users.

Caution

To reiterate, the nebari-git namespace is modified using nebari-config deployments only, and any modifications to the global namespace will only be available locally.

Note

While it is not possible to interact with these namespaces directly, it is possible to override the conda-store permission model to allow users to modify the environments. For more information please refer to Handle Access to restricted namespaces