Knowledge Base/Canopy/Introduction to Canopy

How do I set PYTHONPATH and other environment variables for Canopy?

Jonathan March
posted this on April 25, 2013 19:33

(Updated October 22, 2013)

Warning: Do not use the PYTHONHOME environment variable. If it is set on your system, remove it following the guidelines below. It is extremely fragile, and if you know enough to use it safely, then you know much more than enough to need this article. Its purpose, quickly swapping among Python installations, is almost always better accomplished by modifying the PATH environment variable or by directly referencing the desired Python executable.

Background

Setting the PYTHONPATH environment variable is an easy way to make Python modules available for import from any directory. It is typically used during early development, before you write a  setup.py module for your package and use it to install your package into a Python installation. PYTHONPATH should not be used to import packages from one Python installation into another one -- while this will sometimes work, it can lead to unexplained crashes and other bugs. If you want to use the same package in two Python installations, install it into each of them, separately. (There are some exceptions with 3rd party packages that are shipped only as part of a Python installation, and which you wish to reference from another Python installation, but this should be avoided whenever possible.)

There is no difference in how Canopy uses PYTHONPATH compared to how EPD or any other Python distribution uses it. You put your code somewhere, point PYTHONPATH to it, and Canopy sees it. What can be different is how you set PYTHONPATH (or any other environment variable required by your Python program).

It's always been easy, and it remains so, to set environment variables in a terminal (a.k.a. shell or command prompt) session, and if you run a program using Canopy Python from such a session, then there is no change at all with Canopy. Likewise if you start the Canopy GUI from a terminal session, it will inherit PYTHONPATH from that session (see the final section of this article).

But if you are starting Canopy from the OS's GUI environment (start menu, desktop shortcut, Spotlight, etc), rather than from a terminal, then PYTHONPATH (or other environment variables required by your Python program) must be set in the OS's GUI. This article describes several ways to set such environment variables so that they will be visible in Canopy.

IPython configuration

Create ~/.ipython/profile_default/startup/00-startup.py containing lines like:

import sys,os,os.path
sys.path.append(os.path.expanduser('~/code/eol_hsrl_python'))
os.environ['HSRL_INSTRUMENT']='gvhsrl'
os.environ['HSRL_CONFIG']=os.path.expanduser('~/hsrl_config')

Please note: a bug in Canopy causes any errors in this file to be silently ignored. If you are not seeing the desired settings, try running 'ipython' at the command prompt to see if it reports any issues. 

Set environment variables at the GUI / desktop level

Windows

Editing environment variables through the Control Panel (System / Advanced / Environment / User) is awkward and error-prone. (If you wish to try it, this article on Stack Overflow gives step-by-step instructions for setting PYTHONPATH using these built-in Windows dialogs.) Rather, we recommend using a friendly utility such as the free Rapid Environment Editor, to back up your existing environment variables and modify or remove them.

One unlikely but possible source of confusion: Windows has two levels of environment variables, System and User (not to be confused with Canopy's System and User virtual environments!) Other than the PATH variable (discussed in more detail in this article), Windows User-level environment variables will take precedence over Windows System-level variables. In general, you should not set the PYTHONPATH environment variable at the System level, only at the User level. 

Mac

See this article on Stack Overflow for discussion and recommendation to use /etc/launchd.conf.  For example you could add a line like this to the /etc/launchd.conf file

setenv PYTHONPATH /Users/myname/tmp:/Users/myname/misc

This line initializes the PYTHONPATH to contain the two directories /Users/myname/tmp and /Users/myname/misc.  You may need to create the /etc/launchd.conf file and edit it using superuser privileges for example using

$ sudo edit /etc/launchd.conf

Update: The main response to this article on Stack Overflow also provides a clear explanation of this process.

Linux

The procedure for Linux depends on your distribution.  If you start Canopy from the command shell as mentioned below you should be able to use the usual procedure for creating and modifying environment variables (for instance by editing ~/.profile).

Run Canopy from a terminal session

If you start Canopy from a terminal (shell, command prompt) session using the "canopy" command, then it will inherit the environment variables of that session. For most users, this will not be convenient for regular use, but it can be very helpful when you are experimenting with a different configuration. The easiest way to start Canopy from a terminal session is to first ensure that Canopy Python is on your PATH, as described here.

 

Comments

User photo
Jonathan March
Enthought

Comment from user for Mac OS X

 I could get it to work by creating the following file in my home directory:
'.launchd.conf'

with the contents (for my case):
launchctl setenv PYTHONPATH $PYTHONPATH
launchctl setenv DYLD_LIBRARY_PATH $DYLD_LIBRARY_PATH

The first statement mirrors my PYTHONPATH for the launch demon and the second does the same for the DYLD_LIBRARY_PATH. The latter is used if the modules you are loading into python require shared libraries.

May 17, 2013 18:34