> ## 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

export const Comments = ({children}) => {
  return <div class="my-4 px-5 py-4 overflow-hidden rounded-2xl flex gap-3 border border-zinc-500/20 bg-zinc-50/50 dark:border-zinc-500/30 dark:bg-zinc-500/10" data-callout-type="comments">
      <div class="w-4">
        <svg width="14" height="14" viewBox="0 0 640 640" fill="currentColor" xmlns="http://www.w3.org/2000/svg" class="w-5 h-5" aria-label="Comments">
            <path d="M320 112C434.9 112 528 205.1 528 320C528 434.9 434.9 528 320 528C205.1 528 112 434.9 112 320C112 205.1 205.1 112 320 112zM320 576C461.4 576 576 461.4 576 320C576 178.6 461.4 64 320 64C178.6 64 64 178.6 64 320C64 461.4 178.6 576 320 576zM280 400C266.7 400 256 410.7 256 424C256 437.3 266.7 448 280 448L360 448C373.3 448 384 437.3 384 424C384 410.7 373.3 400 360 400L352 400L352 312C352 298.7 341.3 288 328 288L280 288C266.7 288 256 298.7 256 312C256 325.3 266.7 336 280 336L304 336L304 400L280 400zM320 256C337.7 256 352 241.7 352 224C352 206.3 337.7 192 320 192C302.3 192 288 206.3 288 224C288 241.7 302.3 256 320 256z" />
        </svg>
      </div>
      <div class="text-sm prose min-w-0 w-full">
        {children}
      </div>
    </div>;
};

export const TroubleshootSolution = ({children}) => <>
    <hr className="my-3 w-full" />
    <details className="mt-3">
      <summary className="cursor-pointer font-semibold text-base mb-1">
        Solution
      </summary>
      <div className="mt-2 ml-4" data-component-part="step-content">
        {children}
      </div>
    </details>
  </>;

export const TroubleshootCause = ({children}) => <details className="mt-3 mb-2">
    <summary className="cursor-pointer font-semibold text-base mb-1">
      Cause
    </summary>
    <div className="mt-2 ml-4" data-component-part="step-content">
      {children}
    </div>
  </details>;

export const TroubleshootTitle = ({children}) => <>
    <p className="m-0 font-semibold text-xl leading-tight mb-2" role="heading" aria-level={3}>
      {children}
    </p>
    <hr className="my-3 w-full" />
  </>;

export const Troubleshoot = ({children}) => <div className="callout my-4 px-5 py-4 overflow-hidden rounded-2xl flex gap-3 border troubleshoot-admonition dark:troubleshoot-admonition" data-callout-type="troubleshoot">
    <div className="mt-0.5 w-4">
      <svg width="14" height="14" viewBox="0 0 640 640" fill="currentColor" className="w-4 h-4" aria-label="Troubleshoot">
        <path d="M541.4 162.6C549 155 561.7 156.9 565.5 166.9C572.3 184.6 576 203.9 576 224C576 312.4 504.4 384 416 384C398.5 384 381.6 381.2 365.8 376L178.9 562.9C150.8 591 105.2 591 77.1 562.9C49 534.8 49 489.2 77.1 461.1L264 274.2C258.8 258.4 256 241.6 256 224C256 135.6 327.6 64 416 64C436.1 64 455.4 67.7 473.1 74.5C483.1 78.3 484.9 91 477.4 98.6L388.7 187.3C385.7 190.3 384 194.4 384 198.6L384 240C384 248.8 391.2 256 400 256L441.4 256C445.6 256 449.7 254.3 452.7 251.3L541.4 162.6z" />
      </svg>
    </div>
    <div className="prose min-w-0 w-full">{children}</div>
  </div>;

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 <Tooltip tip="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.">conda package</Tooltip> from a given recipe. Prior knowledge of <Tooltip tip="A command line tool for building conda packages from recipes.">conda-build</Tooltip> 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.
</Note>

1. Install [Miniconda](/getting-started/miniconda/main) or [Anaconda](/getting-started/anaconda/main).

2. If you installed Miniconda, you also need to install the `conda-build`, `anaconda-client`, and `anaconda-navigator` packages. Open an [Anaconda Prompt](/reference/glossary#anaconda-prompt) (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](/tools/anaconda-org/accounts).

   <Note>
     Your Anaconda.org username is the same as your Anaconda.org channel name.
   </Note>

## 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
  ```
</Note>

## 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.
</Note>

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.
   </Comments>

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:

     <CodeGroup>
       ```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
       ```
     </CodeGroup>
   </Note>

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` <Tooltip tip="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.">conda environment</Tooltip>. To return to your base environment, run the following command:

     ```sh theme={null}
     conda activate base
     ```
   </Warning>

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.
   </Warning>

   <CodeGroup>
     ```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
     ```
   </CodeGroup>

For more information about Anaconda.org, see the [Anaconda.org documentation](/tools/anaconda-org/key-features).

## 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.

   <Tabs>
     <Tab title="Windows">
       From the Start menu, search for "Anaconda Navigator" and click to open.
     </Tab>

     <Tab title="macOS">
       Open Launchpad, then click the Anaconda-Navigator icon.
     </Tab>

     <Tab title="Linux">
       1. Open a terminal window.
       2. Open Navigator by using the following command:

          ```sh theme={null}
          anaconda-navigator
          ```
     </Tab>
   </Tabs>

2. To add your <Tooltip tip="A location (URL or file path) in a repository where conda looks for packages.">channel</Tooltip>, 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**.

   <Frame>
     <img src="https://mintcdn.com/anaconda-29683c67/IBO7780zo4xe9zAp/images/add-channel.png?fit=max&auto=format&n=IBO7780zo4xe9zAp&q=85&s=2c7dfc96a2daf51bfc7f28804692f523" alt="" width="858" height="598" data-path="images/add-channel.png" />
   </Frame>

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

## Troubleshooting

<Troubleshoot>
  <TroubleshootTitle>
    ### Custom Navigator app isn't appearing on the Home page
  </TroubleshootTitle>

  <TroubleshootCause>
    Apps may 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.
  </TroubleshootCause>

  <TroubleshootSolution>
    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.
  </TroubleshootSolution>
</Troubleshoot>

<Troubleshoot>
  <TroubleshootTitle>
    ### Custom Navigator app won't launch
  </TroubleshootTitle>

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

  <TroubleshootSolution>
    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.
           </Note>

    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.
  </TroubleshootSolution>
</Troubleshoot>

## Additional Information

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