> ## Documentation Index
> Fetch the complete documentation index at: https://anaconda.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Building Anaconda Navigator applications

In this tutorial, you will learn how to add a tile to Anaconda Navigator that launches your custom application.

Using the JupyterLab feedstock as a base, you'll make modifications to files in the build recipe to declare the package as an application for Navigator, then rebuild it and upload it to an Anaconda.org channel. We'll then add the channel in Navigator, causing the application to appear as a tile on the Home page.

## Who is this for?

This tutorial is for users who want to generate an Anaconda Navigator app conda package (An archive file containing a software program and all its dependencies for easy installation. Conda automatically handles dependency tracking across different platforms, eliminating the need to manually install each component separately.) from a given recipe. Prior knowledge of conda-build (A command line tool for building conda packages from recipes.) or conda recipes is recommended.

## Prerequisites

> [!NOTE]
>
> Any application you intend to launch from Anaconda Navigator should include a Graphical User Interface (GUI) component. Not all conda packages have graphical interfaces.

1. Install [Miniconda](https://anaconda.com/docs/getting-started/installation.md) or [Anaconda](https://anaconda.com/docs/getting-started/installation.md).

2. If you installed Miniconda, you also need to install the `conda-build`, `anaconda-client`, and `anaconda-navigator` packages. Open an Anaconda Prompt (A command-line application included with Windows installations of Anaconda Distribution and Miniconda. Find it by searching 'Anaconda Prompt' in the Windows Start menu.) (Terminal for macOS/Linux users) and run the following commands:

   ```sh theme={null}
   # Ensure conda is up to date
   conda update --name base conda

   # Install conda-build
   conda install --name base conda-build anaconda-client anaconda-navigator
   ```

3. If necessary, [create an account on Anaconda.org](https://anaconda.com/docs/anaconda-org/accounts.md).

   > [!NOTE]
   >
   > Your Anaconda.org username is the same as your Anaconda.org channel name.

## Using a recipe

1. Make a new directory called myapp and then change to the new directory:

   ```sh theme={null}
   mkdir myapp
   cd myapp
   ```

2. Create the recipe by opening a text file and naming it `meta.yaml`.

3. For this tutorial, we will use the jupyterlab recipe yaml from the [jupyterlab feedstock](https://github.com/anacondarecipes/jupyterlab-feedstock/blob/master/recipe/meta.yaml) as a base.

> [!NOTE]
>
> Because JupyterLab is already an application in Navigator, you must change the `name:` parameter in the example jupyterlab `meta.yaml` to make sure that the app appears properly in Navigator.
>
> ```sh theme={null}
> package:
>   name: my-test-app
> ```

## App parameter in `meta.yaml`

The `app:` parameter in the `meta.yaml` file declares a conda package to be an app. The app parameter can contain four keys: `entry`, `summary`, `icon`, and `type`.

```sh theme={null}
app:
  entry: jupyter lab
  icon: icon.png
  summary: JupyterLab {{ version }}
  type: desk
```

* `entry`: The command required to run the package
* `icon`: (Optional) The path to an image you want to appear on your app's tile in Navigator.
* `summary`: A short description of the app.
* `type`: The application type, such as `desk` for desktop application or `web` for a web application.

## Build

Now that you have the `conda-build` recipe ready, you can use the `conda-build` tool to create the package.

> [!NOTE]
>
> You must build and upload your app separately on Windows, macOS, and Linux machines in order for the package to be available on all platforms.

1. Navigate to your `myapp` directory by running the following command:

   ```sh theme={null}
   cd <PATH-TO-DIRECTORY>/myapp
   ```

   Comments

   Replace \<PATH-TO-DIRECTORY> with the file path to your `myapp` folder.

2. Build your application by running the following command:

   ```sh theme={null}
   conda build .
   ```

3. When conda-build is finished, it displays the exact path and filename of the conda package. See the [Troubleshooting](https://docs.conda.io/projects/conda-build/en/latest/user-guide/tutorials/build-pkgs-skeleton.html#troubleshooting) section if the conda-build command fails.

   > [!NOTE]
   >
   > The path and filename will vary depending on your installation and operating system. For example:
   >
   > ```sh Windows theme={null}
   > C:\Users\<USERNAME>\miniconda\conda-bld\win-64\my-test-app-1.2.4-py38_0.tar.bz2
   >
   > ```
   >
   > ```sh macOS theme={null}
   > /Users/<USERNAME>/anaconda3/conda-bld/osx-64/my-test-app-1.2.4-py38_0.tar.bz2
   >
   > ```
   >
   > ```sh Linux theme={null}
   > /home/username/miniconda/conda-bld/linux-64/my-test-app-1.2.4-py38_0.tar.bz2
   > ```

4. Save the path and filename information for the upload step.

## Upload to Anaconda.org

Now you can upload the new local packages to Anaconda.org.

1. First, log in to Anaconda.org from your terminal by running the following command:

   ```sh theme={null}
   anaconda login
   ```

2. Provide your Anaconda.org username and password. If the login is successful, you will see output similar to the following:

   ```sh theme={null}
   Using Anaconda.org api site https://api.anaconda.org

   Username: jsmith
   jsmith's Password:
   login successful
   ```

   > [!WARNING]
   >
   > The following step must be done in the `base` conda environment (An isolated folder containing specific conda packages and dependencies that won't interfere with other projects. Each environment maintains its own versions of libraries and packages, so changes in one environment don't affect others.). To return to your base environment, run the following command:
   >
   > ```sh theme={null}
   > conda activate base
   > ```

3. Now that you are logged into your channel, you can upload the JupyterLab package. Choose a command that works for your operating system:

   > [!WARNING]
   >
   > Change your username, path, and filename to the exact username, path, and filename you saved when you built the application. These will vary depending on your installation and operating system.

   ```sh Windows theme={null}
   anaconda upload C:\Users\<USERNAME>\miniconda\conda-bld\win-64\my-test-app-1.2.4-py38_0.tar.bz2
   ```

   ```sh macOS/Linux theme={null}
   anaconda upload /Users/<USERNAME>/miniconda/conda-bld/osx-64/my-test-app-1.2.4-py38_0.tar.bz2
   ```

For more information about Anaconda.org, see the [Anaconda.org documentation](https://anaconda.com/docs/anaconda-org/key-features.md).

## Configure Anaconda Navigator

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

1. Open Anaconda Navigator.

   > [tab] Windows
   >
   > From the Start menu, search for "Anaconda Navigator" and click to open.

   > [tab] macOS
   >
   > Open **Anaconda Navigator** from your Applications folder.

   > [tab] Linux
   >
   > 1. Open a terminal window.
   > 2. Open Navigator by using the following command:
   >
   >    ```sh theme={null}
   >    anaconda-navigator
   >    ```

2. To add your channel (A location (URL or file path) in a repository where conda looks for packages.), click **Channels**, then **Add**. Enter the URL to your Anaconda.org channel: `https://conda.anaconda.org/{CHANNEL}`, replacing `{CHANNEL}` with your Anaconda.org username.

3. Press Enter (Windows)/Return (Mac) and click **Update Channels**.

   ![](https://mintcdn.com/anaconda-29683c67/Aty9w0mqC-G2DD7s/images/anaconda-desktop/add-channel.png?fit=max\&auto=format\&n=Aty9w0mqC-G2DD7s\&q=85\&s=6dea9b9e34ebc8f35940cbfc00eb45d8)

4. Close and restart Anaconda Navigator. Your app will be displayed on the Home page.

## Troubleshooting

Troubleshoot

### Custom Navigator app isn't appearing on the Home page

***

<details>
  <summary>Cause</summary>

  Apps might not appear on the Home page if the conda package hasn't been uploaded to your Anaconda.org channel, your channel isn't in the Channels list, or Navigator's configuration information is corrupted.
</details>

***

<details>
  <summary>Solution</summary>

  1. Check that the conda package has been uploaded to your Anaconda.org channel.
  2. Check that your channel has been added to the Channels list.
  3. Remove the `.anaconda/navigator` folder from your home directory to reset Navigator's configuration information, then restart Navigator.
</details>

Troubleshoot

### Custom Navigator app won't launch

***

<details>
  <summary>Cause</summary>

  The app can fail to launch due to Navigator configuration issues, even if the application itself is functioning correctly.
</details>

***

<details>
  <summary>Solution</summary>

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

     ```sh theme={null}
     conda run jupyter lab
     ```

     > [!NOTE]
     >
     > If you are not using the example feedstock, the command after `run` will be the `entry:` command you have designated.

  2. If JupyterLab starts correctly with conda, remove the `.anaconda/navigator` folder from your home directory to reset the Navigator configuration information and enable the app to launch correctly from the Navigator application. Then, restart Navigator.
</details>

## Additional information

For more information about adding Start Menu entries in Windows, see the [menuinst](https://github.com/conda/menuinst) documentation.