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.

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 Core install, 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 Core

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 and System environments without a setup GUI

Note

This section is obsolete. Need to add something about using EDM when we decide on the canonical way to set up user environments.

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. This will not work if you are remotely connected to the machine via a text-only interface such as ssh. 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 Canopy\app\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: Creating a Canopy common install

On multi-user systems, Canopy supports “common install” setup, where users share a common Python and set of packages, installed in a central location. This reduces disk usage because there is no need for packages to be duplicated across users. It also provides a consistent set of package versions for all users.

Starting with Canopy 1.6, Canopy’s “open common install” (originally named just “common install”) is not recommended for most users. This feature has been removed in Canopy 2.0. The new recommended method for installing Canopy for multiple users is the “managed common install”. For information about these options, please read the Knowledge Base article “Canopy Common Install Options”.