Canopy Command Line Interface (CLI)

If, like most users, you do not share a machine and want the ability to use both the Canopy GUI and the command line, then you probably do not need to use the Canopy Command Line Interface (CLI).

The Canopy CLI is primarily intended for use in multi-user or command-line-only (non-GUI) configurations, by users comfortable working at the system command prompt. In particular, it is useful for administrators writing automation scripts for Canopy, such as for cluster deployments.

This section covers details of the CLI, installation of Canopy via the command line in a non-GUI environment, and configuring Canopy for use in a multi-user environment.

Note

Canopy before version 2.0 used layered virtual environments for its User Python environments. Canopy 2.0 no longer supports these legacy virtual environments. All newly created User Python environments in Canopy 2.0 and above are non-virtual, single-layer, self-contained Python environments.

Therefore, the CLI options for working with virtual environments are removed in Canopy 2.0. For information about these options, please see the documentation for Canopy 1.7.4.

Canopy 2.0 uses the Enthought Deployment Manager (EDM) to create and manage all new User Python environments. See the EDM documentation for details about EDM’s CLI, which can be used to manage new Canopy User Python environments from the command line.

Command line interface

The Canopy Command Line Interface (CLI) is available via the canopy_cli command, available both in the Canopy application installation, and in the Canopy User Python environment. The tables at the end of this sub-section list the default install paths for the Canopy CLI, on each operating system.

The canopy_cli command has the following sub-command structure:

canopy_cli [<sub-command>] [options] [positional arguments]

The following table shows the available sub-commands and their options and arguments.

Function Sub-command usage
Create a common install post-install-setup [-h] <various options>

The CLI can also be run with no sub-command, as described below in these sections:

Canopy CLI’s default location in the Canopy Application

Platform Version Location
Windows 7 and above 64 C:\Users\<username>\AppData\Local\Enthought\Canopy\App\Canopy_cli.exe
Windows 7 and above 32 C:\Users\<username>\AppData\Local\Enthought\Canopy32\App\Canopy_cli.exe
Mac OS X 64 /Applications/Canopy.app/Contents/MacOS/Canopy_cli
Linux 64 ~/Canopy/canopy_cli

Canopy CLI’s default location in the Canopy User Python environment

Platform Version Location
Windows 7 and above 64 C:\Users\<username>\AppData\Local\Enthought\Canopy\edm\envs\User\Scripts\canopy_cli.exe
Windows 7 and above 32 C:\Users\<username>\AppData\Local\Enthought\Canopy32\edm\envs\User\Scripts\canopy_cli.exe
Mac OS X 64 ~/Library/Enthought/Canopy/edm/envs/User/bin/canopy_cli
Linux 64 ~/.local/share/canopy/edm/envs/User/bin/canopy_cli

Scenario: Setting up the User environment without a setup GUI

Normally, when Canopy is launched for the first time by clicking on its icon, it will set up the user’s Python environment, and perhaps pop up dialog windows with questions. However, when you remotely connect to the machine via a text-only interface such as ssh, the GUI application will not normally start. In such a scenario, you can perform the environment setup without a GUI, by using the CLI post-install-setup --setup-user-env option:

Platform Commmand
Windows C:\Users\<username>\AppData\Local\Enthought\Canopy\edm\envs\User\Scripts\canopy_cli.exe post-install-setup --setup-user-env
Mac OS X /Applications/Canopy.app/Contents/MacOS/Canopy_cli post-install-setup --setup-user-env
Linux ~/Canopy/canopy_cli post-install-setup --setup-user-env

The user’s Python environment will be created in the same default directory as if Canopy had been launched with a normal GUI dialog (Where are all of the Python packages in my Canopy Python Environments?). If you are a Canopy premium support subscriber, and need to change the location of the user’s Python environment, please contact Enthought Support for instructions.

Note about file permissions on Mac and Linux

The setup commands shown above should generally be run as an admin user, but not as the root user, i.e. not using default sudo. You would need to ensure that the admin user has write access, and that all ordinary users have read and execute access, to the target directory (/usr/local/Canopy in this example, or whatever target directory you choose).

Scenario: Update canopy and edm entry points

The Canopy (i.e. canopy and canopy_cli) and EDM entry points (i.e. edm), that are found in each Canopy-managed python environment, depend on the position of the Canopy installation folder. This means that on upgrading canopy these entry points might become invalid. The check and update will normally happen on Canopy GUI start-up, but when running the Canopy GUI application this is not possible, so the post-install-setup subcommand allows you to manually update the entry-points, by using the CLI post-install-setup --fix-scripts option:

Platform Commmand
Windows C:\Users\<username>\AppData\Local\Enthought\Canopy\edm\envs\User\Scripts\canopy_cli.exe post-install-setup --fix-scripts
Mac OS X /Applications/Canopy.app/Contents/MacOS/Canopy_cli post-install-setup --fix-scripts
Linux ~/Canopy/canopy_cli post-install-setup --fix-scripts

Note

The --fix-scripts option should only be used from a command line terminal when calling the canopy_cli directly from the Canopy application install folder. Using the --fix-scripts option inside a Canopy command prompt terminal will fail.

Scenario: Canopy Managed Common Install

Canopy v2 supports a Managed Common Install that provides all users with the same set of Python environments, managed by system administration. This is well suited to production environments, classrooms, and other institutions that wish to ensure a uniform set of centrally managed packages for all users. For more info on the advantages and limitations of this configuration, please read the Knowledge Base article “Canopy 2 Managed Common Install”.

Note

Canopy 1.6 and 1.7 supported a common install setup, using virtual environments inheriting from a shared central environment.. For more information please read the Knowledge Base article “Canopy 1.6 and 1.7 Common Install Options”.

Setup

On an windows command line (i.e. cmd.exe) shell, with administrator privileges, install canopy using the following:

msiexec.exe /l*vm install.log /i "<canopy msi>" /qr SETUP_MANAGED_COMMON_INSTALL="<environments root>" ALLUSERS=1
SETUP_MANAGED_COMMON_INSTALL – The path where the Canopy
managed python environments are stored. Normal users are expected to have permission to read and execute files in this folder.
ALLUSERS=1 – The canopy application will be installed in
Program Files (or Program files (x86) when using Canopy32).

After installation each user should be able to launch Canopy from the Windows Start menu. The Canopy application should be able to switch between the available environments that the system administrator has set up.

Manage shared environments

To start a maintenance session the administrator needs to set up the managed EDM environments to allow changes and toggle them back when finished. This is achieved using the canopy cli tool with the edm subcommand and the mark-read-write, mark-read-only directives:

Platform Commmand
Windows C:\Users\<username>\AppData\Local\Enthought\Canopy\edm\envs\User\Scripts\canopy_cli.exe edm <directive>
Mac OS X /Applications/Canopy.app/Contents/MacOS/Canopy_cli edm <directive>
Linux ~/Canopy/canopy_cli edm <directive> 
<canopy-cli-path> edm mark-read-write
# ... enable edm environment maintenance operations through the Canopy
# ... Command Prompt and the Canopy Package Manager.
<canopy-cli-path> edm mark-read-only
# ... disable such operations.

Once EDM python environments have been marked as read/write the administrator should be able to start Canopy and use the Canopy Package Manager or the Canopy Command Prompt or Terminal.

Warning

  • All maintenance operations normally will require administrative privileges. In Windows, this will typically require starting Canopy “As Administrator”.
  • It is important that the edm mark-read-only subcommand be issued as soon as the maintenance session is finished.
  • Users should not run Canopy or use any of the Canopy-managed Python environments during maintenance operations.

For changes, troubleshooting, use-cases and advanced uses of managed common install please refer to “Canopy 2 Managed Common Install”.