Installing the Shady Package

Summary

python -m pip install shady
python -m Shady demo showcase

Shady is a Python package. Python is a powerful, intuitive language, although it can be difficult to install. Fortunately, it is worth the one-time effort required to set up.

Out of the box, Shady should work on typical modern Windows and macOS systems running either Python 2.7 or Python 3.4+. Other systems may be supportable with a little extra effort. Real-time performance is optimized on Windows; anywhere else, your mileage may vary more. See the Compatibility documentation for more details.

If you already have a Python environment that you use for development

The primary and recommended way to get Shady is to use the pip package manager. You should already have this, if your Python version is reasonably up-to-date (Python 2 versions 2.7.9 and up, or Python 3 versions 3.4 and up). If not, see the pip installation instructions. Assuming you have pip, the following command will install Shady:

python -m pip install Shady

This will automatically download the latest distribution from its home at http://pypi.python.org/pypi/shady , and install it. It will also automatically install the recommended third-party packages (numpy, pillow, matplotlib, and ipython) if you do not already have them. (If you do not want this to happen, you can explicitly prevent it by adding the --no-dependencies flag.)

Test your Shady installation using the interactive script examples/showcase.py:

python -m Shady demo showcase

If you are new to Python development

macOS and Linux distributions come with Python included. However, since other parts of the OS rely on it, your system manages the packages that it contains. Therefore, for your own development work, it is advisable to have a completely separate installation of Python. For scientists, the Anaconda distribution is a good choice.

On Windows, Python doesn’t ship as part of the operating system, but there are many ways to install it. If you find that you already have a Python installation, no integral part of the OS itself will be relying on it, but you should still double-check that there are no third-party tools or applications that use it, before you make any changes. If in doubt then, as for other operating systems, it may be a good idea to install a clean separate Python distribution for your development work. And again, Anaconda is a good choice.

Follow these instructions if you just want to get going with Shady as quickly as possible and aren’t familiar with the many ways to install Python.

  1. Install an Anaconda distribution of Python. We recommend installing a 64-bit Python 3 (at the time of writing the latest release is 3.7). But if you have specific reasons for needing Python 2, Shady is also compatible with Python 2.7.

    OR:

    If you want to avoid installing Anaconda’s giant 3 GB library of third-party packages, you can download the 50 MB bare-bones Miniconda version instead, and install Shady’s recommended third-party packages yourself (see below).

  2. Launch the Anaconda Prompt, which is simply a command prompt that starts off inside your new Python environment.

  3. If you installed the bare-bones Miniconda, install Shady’s four basic recommended dependencies yourself, using the following command:

    python -m conda install  numpy pillow matplotlib ipython
    
  4. (Optional) If you want to use Shady’s video playback and recording features, you will need to install one more package, opencv, which (at the time of writing) is available via conda for some Python versions:

    python -m conda install  opencv
    

    but if that is unavailable or reports a conflict, you can fall back to using the more standard Python package manager, pip (note the change to the package name):

    python -m pip install  opencv-python
    
  5. Install Shady, also using pip:

    python -m pip install  Shady
    
  6. That’s it! Experience some of Shady’s numerous features with the interactive script examples/showcase.py by typing:

    python -m Shady demo showcase
    

Using the right Python

As explained above, any system may have multiple Python distributions. And any Python distribution may have multiple “virtual environments” which are separate silos into which you can install independent sets of packages. Anaconda distributions even have the ability to manage and switch between different versions of the Python interpreter itself in different environments.

All of this means that, before you type python at a system command prompt, you should take care to ensure that it will launch the version/configuration of Python that you intend. (This in turn means that there is no one-size-fits-all set of instructions for installing a given Python package, which explains why this page is so long…)

Anaconda distributions come with a script called activate that allows you to deal with this issue. You would call this once at the beginning of your console session, and it will configure your PATH and other environment variables for the remainder of the session, such that the Anaconda version of Python answers when you call python. On Windows that looks like:

> call C:\PATH\TO\ANACONDA\Scripts\activate.bat

and on others:

$ source /PATH/TO/ANACONDA/bin/activate

By default this puts you in an Anaconda environment called root. But if you have set up other environments, you can pass the name of another environment to the activate script in order to switch to it.

On Windows, the even-simpler way is just to double-click on the shortcut to the Anaconda Prompt, which will open a console window and perform the activate step automatically. We recommend using the Anaconda Prompt whenever you use Python interactively.

If you are using a non-Anaconda distribution of Python, you may have to roll your own solution for configuring the PATH variable appropriately.

Updating your Shady installation

If you installed with pip as above, then the following command is recommended for updating:

python -m pip install --upgrade Shady --no-deps

(you can omit --no-deps if you don’t mind it also upgrading Shady’s various third-party dependencies).