Canopy 1.6 and 1.7 Common Install Options

The Canopy Command Line interface (CLI) includes powerful features for system administrators to create multi-user and automated Canopy installations. 

This article describes the most frequent use of the CLI -- the "common install", for sharing an installation efficiently among multiple users.

Beginning with Canopy 1.6.1, the common install procedures have been greatly streamlined. There are now two kinds of common install, the "managed common install" (recommended in most cases) and the "open common install" (flexible but fragile).


The key advantages of a common install, in contrast to a default shared installation with multiple users, are:

  • Updating library packages is usually done by the central administrator on behalf of all users (rather than by each individual user). This is particularly useful when the users are not skilled Python developers or when you want all users to use the same package versions.
  • The Python environments which Canopy creates for each user are either nonexistent (for a managed common install) or very lightweight (for an open common install); compare this to hundreds or thousands of MB per user with a default multi-user installation. This is particularly useful when there are constraints on the size of user home directories (roaming profiles or limited disk storage).

A common install results in a 2-level or 3-level set of virtual environments:

Level 0: A Canopy Core base environment, installed by an administrator (from the MSI on Windows, .dmg on Mac, or shell script on Linux), on either a local machine or a central server. 

Level 1: A common System (GUI application) virtual environment and User Python virtual environment, inheriting from Level 0, created by the administrator using the Canopy Command Line Interface (CLI), on either a local machine or a central server.

Level 2 (open common install only): A System and User environment for each user, inheriting from Level 1, created (by default) in each user's home directory the first time they start Canopy; these are very lightweight.

Please see "Where are all of the Python packages in my User Python Environment?" in the Canopy User Guide, for an overview of Canopy's use of virtual environments.

Managed Common Install

Beginning with Canopy 1.6, the recommended method for installing Canopy for multiple users is the "managed common install". It provides all users with the same Python environment, managed by system administration. This is well suited to production environments, classrooms, and other institutions that wish to ensure a uniform set of packages for all users.

The key advantages of a managed common install, compared to previous methods, are:

  • Updating library packages is done by the system administrators on behalf of all users (rather than by an unpredictable mix of admin and individual users).  
  • System administrators can update the Canopy package set without assessing whether it is necessary to clean out the superseding environments of individual users.
  • System administrators can update the Canopy GUI application without being superseded by individual users.
  • Canopy's footprint in the home directories of individual users is very light (no Python environments; just configuration, preference, log, and macro script files, typically occupying less than 1 MB, mostly log files). 

A standard managed common install results in two levels of System and User virtual environments, just as in a default individual Canopy installation. The difference is that these environments are managed by system admin, and are available for direct use, but not modification, by individual users.

As an additional option on Windows-64-bit and Linux-64-bit, a managed common install can be configured so that the Canopy User environment is replaced by Canopy's optional flat (no virtual environment) standalone Enthought Python Distribution (EPD), version 7.5 or higher. This configuration completely separates the maintenance of the user's Python & packages, from maintenance of the Canopy GUI application, while still allowing user scripts to run on EPD, from within the Canopy GUI.

Open Common Install

For advanced classroom environments where admin control is not as important, and the students should be permitted to update their own packages or install additional packages, the "open common install" may be suitable. 

An open common install results in the same two levels of System and User virtual environments, as in a managed common install, plus a third layer in the user's individual profile, where the user can install or update packages.

An admin with full access to the Common User environment can update packages there using the "enpkg" command-line utility (after manually activating that environment.) Any updates that she performs in Common environments (whether of the Canopy GUI application or of packages) are inherited by all other users (running in level 2 environments). To make such updates in Common environments, the admin may again need to open the command session with escalated admin privileges.

Because the individual Level 2 user environments always supersede the common Level 1 environment, some common updates will be inherited by some individual users but not by others. Therefore, Open Common Install must be maintained and used with care and skill, and is not recommended for most organizations.


Common installs are now done using the Canopy CLI's "post-install-setup" command, described in  "Canopy CLI post-install-setup options".  

Step-by-step procedures for the most frequently encountered scenarios: 

"Installing Canopy on Windows for classroom/lab use".

For institutional sysadmins: "Installing Canopy to work with Canopy's stand-alone Python distribution (EPD)".


Please do not enter support requests in article comments

Please use article comments for suggestions to improve the article. For individual support requests, please follow these guidelines.

Have more questions? Submit a request


  • Avatar
    Jonathan March

    Updated to clarify permissions issues on Mac and Linux (notably, not installing as root).

  • Avatar
    Stephen Heermann

    The procedure worked, but I have never had to do that with any other software installation.  What is unique about the Canopy Installation (in layman's terms)?


    Do you recommend that the All-user version of Canopy be installed with the Python27 (or Python33) directory, within the program files directory, or with a c:\canopy\ directory?

  • Avatar
    Jonathan March

    Clarified Windows step 1 to make explicit that escalated command prompt may also be needed for subsequent steps.

  • Avatar
    Jonathan March

    Major revision for the new, greatly streamlined, Managed Common Install option in Canopy 1.6.1

  • Avatar
    Jonathan March
    Edited to reflect change in Canopy 1.6.2 in how to update common packages in an Open Common Install.
Powered by Zendesk