.. _package_manager:
Package Manager
===============
Canopy's Package Manager makes it easy to discover and manage the Python
packages available with your Canopy subscription. It provides a convenient
way to:
- find available packages and install them into your Canopy User Python
or EPD environment
- view, update, and remove installed packages
The Package Manager can be opened from the Canopy Welcome screen, or the Canopy
Tools menu. Some Package Manager functionality depends on your subscription
level. Currently the Package Manager only shows and manages packages installed
from Enthought-format package repositories (either managed by Enthought or by
your organization). Specifically, it does *not* know about packages installed
from the command line with pip, setuptools, etc.
.. note::
Starting with version 2.0, Canopy uses a new
`EDM `_ based backend for User
Python environments instead of the older venv-based environments. This was
done to facilitate more robust environment and package management. This page
documents Package Manager usage with the new `EDM` backend. If you are still
using the older venv based user environment in Canopy 1.x, then see the older
Package Manager documentation `here `_.
Overview of Components
----------------------
.. image:: packman2-main-view-labeled.png
1. **Navigator:** (on the left) selects which component to display in the
main pane (Installed packages, Available packages, Updates available, History,
or Settings).
2. **Main pane:** displays whichever pane you select in the Navigator.
Typically, it shows one of the three packages panes, with the package list at
the top, and details about the selected package at the bottom.
3. **Search bar:** filters the list of packages to be shown in the package
panes, by searching package names and summaries.
4. **Login:** displays the email address of the user currently logged in to
Canopy. To log in with your Enthought credentials, go to the Canopy Welcome
Screen. You must be logged to have access to all the packages available with
your subscription.
5. **Refresh:** click to refresh the list of available packages and package
versions. This is useful when a new package or version has been added to the
package repositories, or your subscription level has been upgraded.
Package Panes - Installed, Available and Updates
------------------------------------------------
.. image:: packman2-package-action-running.png
These panes show three different sets of Python packages:
- **Installed:** Shows all packages currently installed in your Canopy User
Python or EPD environment.
- **Available:** Shows all packages available to you in your currently active
repositories, including packages already installed. To learn more about
active and available repositories, please see
":ref:`package_manager_settings_pane`" ("Server" section), below.
- **Updates:** Shows all packages that are already installed but for which a
newer version is available to you in the active repositories. An "Update
all" button is also provided as a convenience, to update all your installed
packages to their latest available versions.
The number of packages in each of these package panes is shown in the Navigator.
Packages are marked with the following status indicators when appropriate:
|orange_bang| Orange bang: an update is available for this package.
|green_checkbox| Green check: this package is installed and up-to-date.
Package details
^^^^^^^^^^^^^^^
When you select a package, the package details section at the bottom of the pane
shows details about that package. This includes a brief searchable summary, a
longer description, the installed version (if applicable), and which versions
are available in the store (package repositories). There are also action buttons
to install / uninstall / upgrade the selected package. When you click on one of
these buttons, that action is queued; it will be performed in the background as
soon as possible; as this happens, the action's detailed steps are shown in the
:ref:`package_manager_history_pane`.
As a convenience, a small information icon |info_icon| appears to the left of
the action buttons while an action is being performed or queued; clicking this
icon takes you directly to the relevant action log in the history pane.
The package details section also shows you which repository the package comes
from (`enthought/commercial` in the above screenshot). It's possible that you
don't have full access to this repository as part of your Canopy subscription.
In this case, the install button changes to an orange "Subscribe to Install"
button which prompts you to upgrade your subscription from the Enthought
website. (You might also see this if you are a subscriber but have not yet
logged in on the Canopy Welcome screen.)
If you only have read access to the Python environment (for example if your
Python installation is completely managed by IT), then you cannot install or
remove packages, so no action buttons will be shown. See the
"Python Environment" section in :ref:`package_manager_settings_pane`.
Search bar
----------
.. image:: packman2-search.png
The top-right of the Package Manager window contains a search bar for quickly
filtering packages within the package panels, based on the package names and
summaries. For example, searching for "plot" would show "matplotlib" and
"plotly" from their package names, and also "basemap" and "chaco" because
"plot" is in those packages' summaries.
The search bar simultaneously filters the packages in all package panes. When
the filter is being used, the counts in the Navigator show not only the total
number of packages in each pane, but also the number of packages that match the
search. You can clear the search bar by clicking on its 'x' icon.
.. _package_manager_history_pane:
History Pane
------------
.. image:: packman2-history-single.png
The history pane shows a list of package actions, with the newest first. Each
line represents the requested installation or removal of one package. An
installation action automatically includes the installation of dependent
packages, and the preliminary removal of other versions (usually older) of any
of these packages.
By default, the history pane lists revisions from all sessions of Package
Manager. Revisions from previous sessions are listed in gray, and their detail
sections show a synopsis of the revision. You can disable showing revisions from
previous sessions in the :ref:`package_manager_settings_pane`.
Selecting an item from the history list shows details of that item in the
bottom pane. For an action which is in progress, this shows a log which is
updated in real time as the steps are performed. For a completed action, a
synopsis is also included, summarizing which packages were installed, removed
and updated. Usually, most of the packages listed in the log or summary will be
the dependencies of the requested package.
When you begin to install/uninstall a package, a line for that action, with
status "In-progress" is added to the top of the history list. When the action
completes, the status changes to "Done", with a revision number marking the
current state of your Python environment.
Queuing and Canceling package actions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. image:: packman2-history-multiple.png
Package actions are executed sequentially. When a package action is executing,
you can see a rotating circle of arrows next to "History" in the Navigator. If
you add an action while others are still running, it is added to the top of the
history list as "Waiting".
You can cancel any waiting action by clicking on the small "x" to the right of
the word "Waiting". You can also click the red button "Cancel all waiting
actions". However you *cannot* cancel actions that are in progress, because that
could break package dependencies in the Python environment. For the same reason,
**please do not close the Package Manager window while actions are in progress.**
.. _package_manager_revert:
Copy package history to clipboard
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|copy_history| If you are communicating with the Enthought support team about
problems in your Python environment, "Copy history to clipboard" can be a useful
diagnostic aid. This small green button is located in the Navigator, to the
right of the word "History". When clicked, it copies the history of package
actions to your clipboard. You can paste this history into a support email or
ticket.
.. _package_manager_settings_pane:
Settings Pane
-------------
.. image:: packman2-settings.png
In the settings pane, you can view your active and available repositories,
repository server URL, Package Manager version information, etc. Some of these
settings can be changed; others are just informative.
**Appearance**
"History" specifies whether to show revisions from previous Package Manager
sessions as well as from the current session. Display of previous sessions can
be temporarily disabled (for the duration of the current session).
**Server**
"Server URL" shows where the package repositories are located. Normally the
server is provided by Enthought, although for licensees of the Enthought
Deployment Server product, this would be on your own server.
"Repositories" shows which package repositories are active, followed by a
dropdown list of inactive available repositories. The level of your Canopy
subscription provides you with access to specific package repositories. You can
select which of these you want to be "active", i.e. where you can immediately
search for packages to install or update. By default, only the enthought/free
and enthought/commercial repositories are active, and the enthought/gpl
repository may optionally be activated (as well as the enthought/ets repository,
and the deprecated, unmaintained enthought/pypi repository).
Note that depending on your type of subscription, you might not have full access
to all your active repositories. For example, free users can activate
and see all the packages in the enthought/commercial and enthought/gpl
repositories, but cannot install these packages without subscribing.
You can activate an available repository by selecting it from the inactive
available repository drop-down list, and clicking "Add". To inactivate an active
repository, click on the "x" button next to its name. Your selection of active
repositories will persist into future Package Manager sessions.
Each active repository is marked with one of the following status icons:
|green_checkbox| Green check: You have full access to view and install
packages in this repository.
|orange_bang| Orange bang: You can view the packages available in
this repository but not install them. Installing these packages requires you
to upgrade your subscription.
|red_warning| Red warning: You have no access to this repository. This
might be shown if another user on your system activated the repository when
they were logged in, but your subscription does not have access to it, or if
it does not actually exist.
**Python Environment**
Shows information about the Python environment (a.k.a. runtime) which the
Package Manager is managing.
The *prefix* label displays the full path to either your Canopy User
Python environment or to your EPD installation.
If you only have read access to the Python environment (for example if your
Python installation is completely managed by IT), then a red warning icon will
show, with accompanying text. In this case, you can not install or remove
packages, only view the various package lists.
The *backend* label displays the backend currently in use by the Package Manager
to manage packages in the User Python Environment. The backend is *edm* for new
User Python environments created in Canopy 2.0.0 or later,
which are managed by EDM, and *enpkg* for User Python environments managed by
enstaller as installed by previous Canopy releases or by EPD.
**About**
Shows version information for the Package Manager and some of its key
dependencies. This information may be useful if you have a problem with the
Package Manager and want to provide full context to the Enthought support team.
.. |green_checkbox| image:: packman2-green-checkbox.png
.. |orange_bang| image:: packman2-orange-bang.png
.. |red_warning| image:: packman2-red-warning.png
.. |info_icon| image:: packman2-info-icon.png
.. |copy_history| image:: packman2-copy-history.png
..
Local Variables:
mode: rst
indent-tabs-mode: nil
sentence-end-double-space: nil
fill-column: 80
End:
Managing packages from the command line using EDM
-------------------------------------------------
.. note::
This section is for advanced users. Whenever possible, packages should
be installed using Canopy's GUI Package Manager.
Starting from Canopy 2.0.0 the Package Manager uses EDM as the backend to
manage packages. It is also possible to manage packages in the User Python
Environment from the command line using EDM directly.
**Please close the Package Manager window before using EDM to manage Canopy
Python environments.**
Then, from the Canopy Tools menu, open a Canopy Command Prompt / Canopy Terminal
window, which will activate the currently active Canopy Python environment
at a command line.
Canopy's ``edm`` executable should then be available in your PATH and accessible
directly at the command line.
You can list the installed packages in your environment with edm's *list*
command::
$ edm list
To install packages use edm's *install* command. E.g. to install ipython::
$ edm install ipython
EDM will prompt you to confirm your requested operation. While EDM is running,
please do not close the Canopy Command Prompt / Canopy Terminal window.
See the `EDM Documentation `_ for
more information on using EDM.