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> |
| 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/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 | ~/.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 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”.