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

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. This environment variable can list one or more directory paths which contain your own modules. On Windows, multiple paths are separated by semicolons. On Mac OS or Linux, they are separated by colons.

PYTHONPATH 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. You only need to do one of these methods. If you need to remove existing paths from an environment variable, then Method B is usually the best choice.

Method A: IPython configuration

Create ~/.ipython/profile_default/startup/00-startup.py (on Windows, replace "~" by your home directory) 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. 

As a side note, if you are using ipython, an alternative to setting PYTHONPATH is Tony Yu's pypath magic: http://tonysyu.github.io/pypath-magic.html

Method B: Set environment variables at the GUI / desktop level

Windows

See the Knowledge Base article "Editing environment variables on Windows".

Mac OS X

OS X <=10.9

See this article on Stack Overflow for a 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

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

OS X 10.10 and above

There is a breakage or removal of environment variable functionality in launchd.conf for users of OS X 10.10 (Yosemite) and above. A solution is to create an environment.plist file which specifies a PYTHONPATH and is executed at system startup. To do this from Terminal:

$ sudo nano  ~/Library/LaunchAgents/environment.plist

Copy and paste the following into the text editor that just opened in Terminal, replacing the bold text with the paths that you wish to include in the PYTHONPATH separated by colons.

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">

<plist version="1.0">

<dict>

  <key>Label</key>

  <string>my.startup</string>

  <key>ProgramArguments</key>

  <array>

    <string>sh</string>

    <string>-c</string>

    <string>

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

    </string>

  </array>

  <key>RunAtLoad</key>

  <true/>

</dict>

</plist>

Save this file (Ctrl-O, then Enter) and exit the text editor (Ctrl-X).

Then run the following to apply the changes.

$ launchctl load ~/Library/LaunchAgents/environment.plist

Note: You may have to restart your computer if the changes did not take effect with the above command.

Please see this Stack Overflow article which describes this issue and workaround. 

Some users have experienced difficulty getting the above to work with OSX 10.11. If this is the case, another option to set PYTHONPATH for Canopy is to use osx-env-sync. This utility reads ~.bash_profile and sets the environment variables exported in this file for GUI applications. Note that if you did not previously have a ~/.bash_profile file, creating one will take precedence over ~/.bashrc and ~/.profile for Terminal sessions. As such, you will need to add a line in ~/.bash_profile to source ~/.profile and/or ~/.bashrc to use those configuration files as well. For more detailed information please go here.

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).

Method C: 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.