Installing Shiny for Python

To install Shiny for Python, first create a new directory for your first Shiny app, and change to it.

mkdir myapp
cd myapp

Next, use either pip or conda to install the shiny package.

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

# Create a virtual environment in the .venv subdirectory
python3 -m venv venv

# Activate the virtual environment
source venv/bin/activate

It is also a good idea 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

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

Running

In the same directory you created above, run:

shiny create .

This will create a basic Shiny application in the current directory, in a file named app.py.

To run the app, run this command from the shell:

shiny run --reload

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. So your workflow is 1) save changes to app.py, 2) wait a moment for the changes to appear in the browser.

Configure Visual Studio Code

While can use any text editor or Python IDE to write Shiny apps, we’ve taken special care to ensure a smooth workflow for Visual Studio Code.

Running Shiny apps

You can run Shiny apps by calling shiny run --reload app.py from any terminal. However, the Shiny extension makes it even easier and more convenient. 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. Click the icon to the right of the URL bar to launch the app in your default browser.

Note that this method of running Shiny apps doesn’t work for interactive debugging; in that case, run your app using the instructions below.

Configuring VS Code type checking

We highly recommend installing the Python extension, which provides many features that assist in writing Python code, including inline type checking.

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.

Using the VS Code Python debugger

The Python extension also adds an excellent Python debugger to Visual Studio Code. Each VS Code project/workspace must indicate how it should be launched for debugging purposes, via a .vscode/launch.json file. For Shiny apps, that file should look like this:

{
  // Use IntelliSense to learn about possible attributes.
  // Hover to view descriptions of existing attributes.
  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Run Shiny app",
      "type": "python",
      "request": "launch",
      "module": "shiny",
      "args": ["run", "${file}"],
      "jinja": true,
      "justMyCode": true
    },
  ]
}

With that file is in place, you can start a debugging session: open your app.py file and run the Start Debugger command (F5). This will attempt to debug shiny run <path-to-current-file>.

If your project contains a single Shiny app, you can replace the "${file}" in the above snippet with the relative path to your app.py file. With a hardcoded path like this, you can press F5 to start debugging your app without having to activate the app.py editor tab first.

Note that in debugging mode, edits to your source code will not result in automatic reloading (i.e. the shiny run command will not have --reload); instead, you will need to restart your debugging session (Command+Shift+F5 / Ctrl+Shift+F5).