Building Anaconda Navigator applications#

This tutorial will build an Anaconda Navigator Application (app) of JupyterLab.

Three modifications to the files in the build recipe are required to declare the package as an app. Then, we’ll build JupyterLab with these recipe modifications. After we build the package, we will upload it to an Anaconda.org channel. Finally, after adding the channel in Anaconda Navigator, the app will appear on the Home pane.

Who is this for?#

This tutorial is for Windows, macOS, and Linux users who wish to generate an Anaconda Navigator app conda package from a given recipe. Prior knowledge of conda-build or conda recipes is recommended.

Before you start#

Note

Applications to be built for Anaconda Navigator should have a graphical user interface. Not all conda packages have graphical interfaces.

You should already have installed Miniconda or Anaconda <../../anaconda/install>. Install conda-build:

conda install conda-build

It is recommended that you use the latest versions of conda and conda-build. To upgrade both packages run:

conda upgrade conda
conda upgrade conda-build

You will also need an account on Anaconda.org. Your username will be referred to as your Anaconda.org channel.

Using a recipe#

First, make a new directory called jupyterlab and then change to the new directory:

mkdir jupyterlab
cd jupyterlab

Create the recipe by opening a text file and name it meta.yaml.

Copy the jupyterlab recipe yaml from the jupyterlab feedstock

Build architecture#

The recipe, as given, is a noarch recipe. This is not compatible with older versions of Navigator. Under the build section, remove noarch: python.

App entry in meta.yaml#

To declare a conda package as an app, the app parameter must be added to to the meta.yaml file. The app section will contain three keys: entry, summary, and type. In the case of the JupyterLab recipe, replace the app section in the meta.yaml with the values below.

In the app section, the entry tag defines how the package is to be launched by Anaconda Navigator. For JupyterLab, separate entry tags are required for Windows, macOS, and Linux operating systems.

Adding entry keys for Windows and Linux#

In your text editor, open the meta.yaml file and add the following lines. On Windows and Linux the entry tag is:

app:
 entry: jupyterlab .                                 [win]

 entry: jupyterlab .                                 [linux]

Adding a launch script for macOS#

For macOS, a launch script must also be provided. In a text editor, create a new file in the conda-build recipe directory called jupyterlab_mac.command. The contents of this file are:

DIR=$(dirname $0)
$DIR/jupyter-lab ${HOME}

Adding an entry key for macOS#

Then in the meta.yaml, add this line to the app section:

entry:
   open ${PREFIX}/bin/jupyterlab_mac.command [osx]

The completed app section should look like this:

app:
 entry: jupyterlab static                         [win]
 entry: jupyterlab static                         [linux]
 entry: open ${PREFIX}/bin/jupyterlab_mac.command [osx]
 summary: jupyterlab
 type: web

Note

The app icon defaults to the Anaconda logo unless specified with a logo: LOGONAME.png line.

Build.sh script#

To make sure that the file gets installed, create a new file in the same directory as the meta.yaml. Title it build.sh and add these lines to the build.sh script:

$PYTHON  -m pip install . --no-deps --ignore-installed -vv
if [ `uname` == Darwin ]

then
    cp $RECIPE_DIR/jupyterlab_mac.command $PREFIX/bin

fi

Remove the script key under the build section in the meta.yaml.

Build.bat#

Create a new file called build.bat. Include the following:

%PYTHON% -m pip install . --no-deps --ignore-installed -vv

Build#

Now that you have the conda-build recipe ready, you can use the conda-build tool to create the package. You will have to build and upload the JupyterLab package separately on Windows, macOS, and Linux machines in order for the package to be available on all platforms. If you’re already in the JupyterLab directory, you can type conda build . in your terminal. Otherwise type conda-build jupyterlab.

When conda-build is finished, it displays the exact path and filename of the conda package. See the Troubleshooting section if the conda-build command fails.

Windows example file path: C:\Users\username\miniconda\conda-bld\win-64\jupyterlab-1.2.4-py38_0.tar.bz2

macOS example file path: /Users/username/anaconda3/conda-bld/osx-64/jupyterlab-1.2.4-py38_0.tar.bz2

Linux example file path: /home/username/miniconda/conda-bld/linux-64/bjupyterlab-1.2.4-py38_0.tar.bz2

Note

The path and filename will vary depending on your installation and operating system.

Save the path and filename information for the next step.

Upload to Anaconda.org#

Now you can upload the new local packages to Anaconda.org. First, log in to Anaconda.org from your terminal: anaconda login

You will be asked for your Anaconda.org account name and password. If the login was successful, you will see output like the following:

Using Anaconda.org api site https://api.anaconda.org

Username: jsmith
jsmith’s Password:
login successful

Caution

This step must be done in the base conda environment.

Now that you are logged into your channel, you can upload the JupyterLab conda package as follows:

Windows users: anaconda upload C:\Users\username\miniconda\conda-bld\win-64\jupyterlab-1.2.4-py38_0.tar.bz2

Linux and macOS users: anaconda upload /Users/username/miniconda/conda-bld/osx-64/jupyterlab-1.2.4-py38_0.tar.bz2

Note

Change your username, path, and filename to the exact username, path, and filename you saved in Step 2. These will vary depending on your installation and operating system.

For more information about Anaconda.org, see the Anaconda.org documentation page.

Configure Anaconda Navigator#

Now that the JupyterLab package has been uploaded to your Anaconda.org channel, you need to add the channel to Anaconda Navigator.

  1. Launch the Anaconda Navigator app. In Windows and Linux, it will be available from the Start Menu. On macOS, you can find it either on the Desktop or through Spotlight.

  2. To add your channel, click Channels, then Add. Enter the URL to your Anaconda.org channel: https://conda.anaconda.org/CHANNELNAME, replacing CHANNELNAME with your Anaconda.org username.

  3. Press Enter and select Update Channels.

  4. Close and restart Anaconda Navigator. The JupyterLab app will be displayed on the Home pane.

Troubleshooting#

A. Conda-build fails#

If the conda recipe fails to build, consult the Troubleshooting guide.

B. App does not appear on the home pane#

Check that the conda package has been uploaded to your Anaconda.org channel. Check that your channel has been added to the Channels list.

You may have to remove your .anaconda/navigator directory and restart Navigator. This directory is in your Home directory.

C. App does not launch#

If the application does not launch after installation, confirm that it works via the command line by running the following: conda run jupyterlab

If JupyterLab starts correctly from conda, you may have to remove your .anaconda/navigator folder from your Home directory to reset the Navigator configuration information and enable it to launch correctly from the Navigator application.

  • In Windows, your Home directory is something similar to C:/Users/<username>. Open the .anaconda folder and right-click to delete the navigator folder.

  • In macOS or Linux, open a new terminal and use rm -rf to delete the .anaconda/navigator folder.

    rm -rf .anaconda/navigator

Once you have deleted the .anaconda/navigator folder, restart the Navigator application.

Additional Information#

For more information about adding Start Menu entries in Windows, see the menuinst documentation.

On this page