Streamlit ========= `Streamlit `__ is an open-source Python library that makes it easy to create and share beautiful, custom web apps for machine learning and data science. No knowledge of web development is needed to get started. Helpful tips can be found by visiting Streamlit’s `Getting Started `__ page. Streamlit also showcases example apps, found in the featured `App Gallery `__. There are many ways to work with Streamlit, whether through a local server or as a Python module. Streamlit also supports `magic commands `__, a feature that provides convenience by removing the need to explicitly write Streamlit commands into your Python script. This feature is enabled by default. **We recommend using VS Code when creating Streamlit apps.** Launch VS Code -------------- Generate VS Code Instance on Notebooks Hub ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Go to `Notebooks Hub `__ and log in with your credentials. .. figure:: ../../img/QA/QA-login-1.png :alt: A screenshot of the Notebooks Hub login page A screenshot of the Notebooks Hub login page .. figure:: ../../img/QA/QA-login-2.png :alt: A screenshot of the Notebooks Hub credentials page A screenshot of the Notebooks Hub credentials page Next, launch VS Code using either of the following two methods. Method 1: Quick Launch ^^^^^^^^^^^^^^^^^^^^^^ From the **Home** page, select VS Code to quick launch the IDE. .. figure:: ../../img/QA/QA-home.png :alt: A screenshot of the Notebooks Hub home page A screenshot of the Notebooks Hub home page Method 2: Custom Server Instance ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Alternatively, use the sidebar navigation panel to select **Servers** and select **Create New** to launch a VS Code instance with additional configurations. .. figure:: ../../img/QA/QA-create-new-server.png :alt: A screenshot of the Notebooks Hub sidebar and dashboard panel A screenshot of the Notebooks Hub sidebar and dashboard panel Next, work through the steps within the server wizard. Steps are illustrated below. 1. Select VS Code under the IDE tab. .. figure:: ../../img/QA/QA-serverlaunch-IDE-VSCode.png :alt: A screenshot of the Notebooks Hub new server steps A screenshot of the Notebooks Hub new server steps 2. Select one of the options provided below. - **Create New File**: Create a new file when launching the server. If selected, the wizard will provide possible file extensions for the new file. - **Upload File**: This option allows the user to upload a file from the local computer onto the server. - **Select File/Folder**: This option points the server to a specific file that already exists on the server. - **Skip**: Launch without pointing to file. This is helpful when launching a fresh instance. .. figure:: ../../img/QA/QA-serverlaunch-selectfile.png :alt: A screenshot of the Notebooks Hub new server steps A screenshot of the Notebooks Hub new server steps 3. Select appropriate virtual hardware to utilize from the server host. In most cases, **Shared Medium CPU** is sufficient. .. figure:: ../../img/QA/QA-serverlaunch-hardware.png :alt: A screenshot of the Notebooks Hub new server steps A screenshot of the Notebooks Hub new server steps 4. Select the appropriate module (i.e., python environment) to load for the instance. The latest **python-data-science** module is a great starting point. Custom environments and modules can be created following the steps outlined inside the **Notebooks Hub UI** `section `__. .. figure:: ../../img/QA/QA-serverlaunch-modules.png :alt: A screenshot of the Notebooks Hub new server steps A screenshot of the Notebooks Hub new server steps 5. Add details to your server instance and click launch. .. figure:: ../../img/QA/QA-serverlaunch-metadata.png :alt: A screenshot of the Notebooks Hub new server steps A screenshot of the Notebooks Hub new server steps After the VS Code instance is created using either method, it will show up on your **Servers** page. The home icon on the top right corner of the instance indicates it was generated with quick launch from the **Home** page. |A screenshot of the VS Code instance created through quick launch| |A screenshot of the VS Code instance created with server wizard| .. |A screenshot of the VS Code instance created through quick launch| image:: ../../img/vscode/vscode-launcher.png .. |A screenshot of the VS Code instance created with server wizard| image:: ../../img/vscode/vscode-server.png Open VS Code ~~~~~~~~~~~~ 1. Open the Navigation Toolbar by clicking the top left corner. .. figure:: ../../img/vscode/vscode-workspace-1.png :alt: A screenshot of VS Code showing step to add folder to workspace A screenshot of VS Code showing step to add folder to workspace 2. Select **File** then **Add Folder to Workspace…**. .. figure:: ../../img/vscode/vscode-workspace-2.png :alt: A screenshot of VS Code showing step to add folder to workspace A screenshot of VS Code showing step to add folder to workspace 3. Select ``home/jovyan/work`` to add the **work** directory to your workspace. Any files saved in your personal **work** directory will persist across user sessions. The **shared** directory (``home/jovyan/shared``) can also be added to your workspace but cannot be edited. The benefits of adding the **shared** directory is to access example datasets and applications. .. figure:: ../../img/vscode/vscode-workspace-3.png :alt: A screenshot of VS Code showing step to add folder to workspace A screenshot of VS Code showing step to add folder to workspace 4. A workspace with your selected folder will now appear in the file explorer. This workspace can be saved and renamed as desired. .. figure:: ../../img/vscode/vscode-workspace-4.png :alt: A screenshot of VS Code showing workspace A screenshot of VS Code showing workspace .. figure:: ../../img/vscode/vscode-save-workspace.gif :alt: A gif showing workspace saving on VS Code A gif showing workspace saving on VS Code If needed, additional directories can be added to the same workspace by right clicking inside the file explorer, clicking **Add Folder to Workspace…**, then selecting your desired folder to add. .. figure:: ../../img/vscode/vscode-workspace-5.png :alt: A screenshot showing how to add folders to workspace in VS Code A screenshot showing how to add folders to workspace in VS Code .. figure:: ../../img/vscode/vscode-workspace-6.png :alt: A screenshot showing how to add folders to workspace in VS Code A screenshot showing how to add folders to workspace in VS Code Parent folders inside the workspace file explorer can be removed from the workspace. Folders removed from the workspace will not be deleted. .. figure:: ../../img/vscode/vscode-workspace-7.png :alt: A screenshot showing how to add folders to workspace in VS Code A screenshot showing how to add folders to workspace in VS Code Install Streamlit ~~~~~~~~~~~~~~~~~ Open Terminal ^^^^^^^^^^^^^ Open terminal window inside VS Code by using the Navigation Toolbar > Click on **Terminal** > Click on **New Terminal**. .. figure:: ../../img/vscode/vscode-terminal.gif :alt: A gif showing how to open terminal in VS Code A gif showing how to open terminal in VS Code If there is more than one parent directory in the workspace, a command window will open at the top of VS code prompting the user to select which directory to set as the terminal’s current path. This initial path can be changed using standard shell commands (e.g., ``cd ``). .. figure:: ../../img/vscode/vscode-terminal-select.png :alt: A screenshot showing terminal path selection in VS Code if more than one folder in workspace A screenshot showing terminal path selection in VS Code if more than one folder in workspace Once the terminal panel loads at the bottom of VS Code, the selected working path for the terminal will be shown before the ``$`` symbol. If there are two or more parent folders in the workspace, the parent folder name will also be shown next to the terminal type (e.g., shown as **bash - work** in image below). Multiple terminal windows can also be opened using the same steps listed above, or simply by clicking on the ``+`` button or ``+`` dropdown. .. figure:: ../../img/vscode/vscode-terminal-dropdown.png :alt: A screenshot of buttons at top right of terminal panel in VS Code A screenshot of buttons at top right of terminal panel in VS Code Multiple terminal windows will appear in a list on the right side of the terminal panel. Use the trashcan icon to delete unnecessary windows as needed. .. figure:: ../../img/vscode/vscode-terminal-multiple.png :alt: A screenshot of multiple terminals listed in panel in VS Code A screenshot of multiple terminals listed in panel in VS Code Installation using pip ^^^^^^^^^^^^^^^^^^^^^^ Activate desired conda environment and install Streamlit using ``pip install streamlit``. Streamlit can also be installed into the default ``base`` conda environment, but note that installations inside ``base`` are temporary. These will be cleared with each new user session (i.e., stopping then restarting the server instance). For more information on creating your own user-defined conda environments, please refer to the the instructions `here `__. .. figure:: ../../img/vscode/vscode-install-streamlit.gif :alt: A gif showing pip installation of streamlit in VS Code A gif showing pip installation of streamlit in VS Code Test proper streamlit installation by typing ``streamlit hello`` into the terminal to launch the introductory demo. .. figure:: ../../img/vscode/vscode-streamlit-hello.gif :alt: A gif showing streamlit hello demo in VS Code A gif showing streamlit hello demo in VS Code Port Forwarding ~~~~~~~~~~~~~~~ Applications are forwarded into different ports. A pop up notification will appear at the bottom right corner of VS Code. Click **Open in Browser** to open a new tab window showing the running application. .. figure:: ../../img/vscode/vscode-streamlit-hello-button.png :alt: A screenshot of the port forwarding notification A screenshot of the port forwarding notification If this notification does not appear or disappears after some time, navigate to **PORTS** in the terminal panel to see any running applications. .. figure:: ../../img/vscode/vscode-streamlit-hello-port.png :alt: A screenshot of the PORT panel in VS Code A screenshot of the PORT panel in VS Code Stop Application Run ~~~~~~~~~~~~~~~~~~~~ Use ``Ctrl+C`` in the terminal to stop the app (i.e., press the ``C`` key while holding down ``Ctrl`` key). Creating a Streamlit App ------------------------ Create app.py File ~~~~~~~~~~~~~~~~~~ 1. Create a new ``.py`` file, commonly named ``app.py`` for simplicity. This can be renamed if desired. Two easy options to create a new file using the VS Code interface are shown below.    **Option 1:** Use Navigation Toolbar > Click on **File** > Click on **New File** .. figure:: ../../img/vscode/vscode-newfile-1.gif :alt: A gif showing method to create new file on VS code. A gif showing method to create new file on VS code.    **Option 2:** In the File Explorer Panel, hover over your workspace name and click on the new file button: |VS Code new file button| .. figure:: ../../img/vscode/vscode-newfile-2.gif :alt: A gif showing method to create new file on VS code. A gif showing method to create new file on VS code. .. |VS Code new file button| image:: ../../img/vscode/vscode-newfile-2-icon.png 2. Inside the terminal, navigate to the proper working directory containing the ``app.py`` file if not already there. The correct path can be obtained by right clicking on the folder name inside File Explorer and selecting **Copy Path**. Then, type ``cd `` into the terminal to change its current path to the proper directory (e.g., ``cd /home/jovyan/work/Streamlit``). .. figure:: ../../img/vscode/vscode-copypath.png :alt: A screenshot showing menu containing copy path A screenshot showing menu containing copy path 3. Test file by entering ``streamlit run app.py`` into the terminal. At this stage, a blank app should appear in your browser as shown below. Use ``Ctrl+C`` to stop app before moving on. .. figure:: ../../img/streamlit/streamlit-blank.png :alt: A screenshot of a blank app A screenshot of a blank app Generate App ~~~~~~~~~~~~ You can now begin writing your app! Use ``import streamlit as st`` to use Streamlit as a Python module. .. code:: sos """ # My first app """ import streamlit as st Use ``streamlit run .py`` in the terminal to preview your app (e.g., rendering, functionality). Previews can also be actively launched while updating your code. If so, the app will let you know in the top right corner that the source file has changed and provide a ``rerun`` button to reload the app. .. figure:: ../../img/streamlit/streamlit-rerun.png :alt: Screenshot of rerun button Screenshot of rerun button Use ``Ctrl+C`` in the terminal to stop the app after launch. Make sure to output a ``requirements.txt`` file listing required Python dependencies for your app. **Note:** Sometimes sensitive credentials or secrets are necessary to develop your app locally. Please visit Streamlit’s `Secrets management documentation `__ for more information.