install-create-run.qmd

---
title: Install, create, & run
aliases:
  - install.html
---

## Install

`shiny` can be installed via `pip` or `conda`.

::: {.panel-tabset .panel-pills}

#### pip

Before installing you may want to upgrade `pip` and install `wheel`:

```bash
pip install --upgrade pip wheel
```

Next, install `shiny` from PyPI.

```bash
pip install shiny
```

You may on occasion need to force installation of updated versions of our packages, since they are in development. This can be done with:

```bash
pip install --upgrade shiny htmltools
```

::: {.callout-note collapse="true"}
##### Virtual environments

For production apps, we recommend using a virtual environment to manage your dependencies. In this case, you should install `shiny` in your virtual environment scoped to your app, rather than globally. For example, if you are creating an app in a directory called `myapp`, you would create a virtual environment in that directory and install `shiny` there:

```bash
mkdir myapp
cd myapp
# Create a virtual environment in the .venv subdirectory
python3 -m venv .venv
# Activate the virtual environment
source .venv/bin/activate
```
:::

::: {.callout-note collapse="true"}
##### Development versions

If you want to install the development versions, you can do so with:

```bash
pip install https://github.com/posit-dev/py-htmltools/tarball/main
pip install https://github.com/posit-dev/py-shiny/tarball/main
```
:::


#### conda

If you want to use a conda environment, feel free to create/activate one now:

```bash
# Create a conda environment named 'myenv'
conda create --name myenv

# Activate the virtual environment
conda activate myenv
```

Next, install `shiny` from conda-forge.

```bash
conda install -c conda-forge shiny
```

You may on occasion need to force installation of updated versions of our packages, since they are in development. This can be done with:

```bash
conda update -c conda-forge shiny
```

:::

### VS Code

We recommend installing the [Python][vscode-python] and [Shiny][vscode-shiny] extensions for [Visual Studio Code][vscode]. This provides, among other things, a play button in the top right corner of your editor that will run your Shiny app.

If [type checking is important](https://john-tucker.medium.com/type-checking-python-306ad8339da1) to you, in addition to installing the [Python VSCode extension][vscode-python], you may want to do some additional configuration for a smooth experience with types in Shiny. See the tip below for more details.

::: {.callout-tip collapse="true"}
##### Type checking

We recommend the following settings in your project's `.vscode/settings.json` file:

```default
{
    "python.analysis.typeCheckingMode": "basic",
    "python.analysis.diagnosticSeverityOverrides": {
        "reportUnusedFunction": "none"
    }
}
```

or alternatively, if your project keeps these settings in `pyrightconfig.json`:

```default
{
  "typeCheckingMode": "basic",
  "reportUnusedFunction":  "none",
}
```

The `basic` type checking mode will flag many potential problems in your code, but it does require an understanding of type hints in Python. This is the mode that is used by the [Shinylive](https://shinylive.io) examples editor. If you want to make even greater use of type checking, you can use `strict` mode:

```default
   "python.analysis.typeCheckingMode": "strict"
```

If you still find that too obtrusive and aren't used to working with type hints, you can remove that line entirely.

In the above configuration, we also disable the `reportUnusedFunction` diagnostic, as it's idiomatic Shiny to create named functions that are never explicitly called by any code (i.e., `@reactive.effect`).

You can also modify these settings on a per-file basis with comments at the top of the file. For example, you might have something like this at the top of your `app.py`:

```default
# pyright: strict
# pyright: reportUnusedFunction=false
```

A full list of configuration settings for Pyright/Pylance is available [here](https://github.com/microsoft/pyright/blob/main/docs/configuration.md).

[vscode]: https://code.visualstudio.com/
[vscode-shiny]: https://marketplace.visualstudio.com/items?itemName=posit.shiny
[vscode-python]: https://marketplace.visualstudio.com/items?itemName=ms-python.python
:::


## Create

The best way to create a new Shiny app is with the `shiny create` command line interface (CLI). This command asks you a series of questions about what kind of app you want to create, and then provides all the boilerplate code you need to get started with a working app.

```bash
shiny create
```

![Running the shiny create command from a terminal](assets/shiny-create.mp4){class="img-shadow"}

::: callout-tip
### Copy/paste examples

If you find an example on this site that you want to run/edit locally, you can use `shiny create --template basic-app -m express` to get a basic app template, and then copy/paste the code from the example into the template.
:::


## Run

Shiny apps can be launched from VSCode or the command line (via `shiny run`).

### VS Code

The best way to run (and develop) Shiny apps is in [Visual Studio Code][vscode] with the [Shiny extension][vscode-shiny]. When a Shiny `app.py` file is being edited, the default behavior of the Run button (circled in red in the screenshot below) becomes "Run Shiny App".

![Visual Studio Code running with the Shiny extension](assets/vscode.png)

This launches a Python process in a dedicated terminal instance, and a captive web browser. This lets you test your app without leaving your editor, and whenever you make changes to your app's source, the preview will update. To preview your app in a full browser, click the icon to the right of the URL bar to launch the app in an external browser.

Next to the Run button is a dropdown menu that lets you "Debug Shiny App". This launches the app in debug mode, which lets you set breakpoints and step through your code. See the [debugging](debug.qmd) section for more information.

### Command line

To run a Shiny app from the command line, use the `shiny run` command. This command takes a single argument, the path to the app's entry point. For example, if your app's entry point is `app.py` in the directory `./app_dir`, you can run it like this:

```bash
shiny run --reload --launch-browser app_dir/app.py
```

This should start your app and also automatically launch a web browser.

The `--reload` flag means that file changes in the current directory tree will cause the Python process to restart and the browser to reload. Update and save changes to `app.py` and then wait a moment for the changes to appear in the browser.

With these two `shiny` commands, you now have a project that you can run in your terminal. You can use any text editor or Python IDE to write Shiny apps, but we've taken special care to ensure a smooth workflow for [Visual Studio Code][vscode]. The next section will help you set up VS Code for Shiny for Python.