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.


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>
Update Canopy update [-h] <venv-directory>
Low-level venv creation venv [-h] [-s] [-u] <directory>
Register a Venv (Windows) register-venv <venv-directory>
Unregister a Venv (Windows) unregister-venv <venv-directory>

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

canopy_cli update

The canopy_cli update command downloads and applies any available updates to the Canopy Application. This is a command-line-only (no GUI popup) convenience, equivalent to “Canopy Application Updates” within the Canopy GUI.

It is possible that several updates could be available, which would need to be applied sequentially. This might occur if your current version of Canopy is a bit old, or for other technical reasons. In this case, one update would be downloaded and applied at each invocation of this update command.

In the case of an update to the Canopy Core environment, the update command’s optional <venv-directory> can point to a venv that was previously created by the user using either canopy_cli venv -s or venv -s. After the updated Core environment has been created, this will be updated so that it inherits from the new Core environment, rather than the old one.

canopy_cli register / unregister

These commands are specific to users running on Microsoft Windows and support integration with Microsoft’s Python Tools for Visual Studio (PTVS) tool. Canopy provides a custom integration that allows PTVS to automatically detect the User Python environment by default. This integration doesn’t have a way to detect Canopy virtual environments created by the user, however, unless it gets a little help.

The register command allows a custom virtual environment to be registered such that it will be automatically detected by Canopy’s PTVS integration and will show up in the list of recognized Python environments in PTVS. The unregister command simply reverses this process and removes the environment from the list.

A typical scenario is to create a venv for a particular application or experiment and then register it to use PTVS to debug the code. For example:

canopy_cli.exe venv -s c:\projects\new_app1      # Constructs the venv as above
canopy_cli.exe register c:\projects\new_app1

After the register command completes the new venv will appear automatically in the PTVS “Python Environments” tab. This environment can be de-registered like this:

canopy_cli.exe unregister C:\projects\new_app1

Note that it can be unregistered even if it has already been deleted as long as the path matches the original location.

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/
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 ~/.canopy/edm/envs/User/bin/canopy_cli

Scenario: Setting up the User and System environments without a setup GUI


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/ 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 User Python Environment?). 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”.