Install, create, & run

Install

shiny can be installed via pip or conda.

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

pip install --upgrade pip wheel

Next, install shiny from PyPI.

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:

pip install --upgrade shiny htmltools

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:

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

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

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

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

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

# Activate the virtual environment
conda activate myenv

Next, install shiny from conda-forge.

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:

conda update -c conda-forge shiny

VS Code

We recommend installing the Python and Shiny extensions for Visual Studio Code. 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 to you, in addition to installing the Python VSCode extension, you may want to do some additional configuration for a smooth experience with types in Shiny. See the tip below for more details.

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

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

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

{
  "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 examples editor. If you want to make even greater use of type checking, you can use strict mode:

   "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 the top of your app.py:

# pyright: strict
# pyright: reportUnusedFunction=false

A full list of configuration settings for Pyright/Pylance is available here.

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.

shiny create

Running the shiny create command from a terminal
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 with the Shiny extension. 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

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

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. The next section will help you set up VS Code for Shiny for Python.