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.
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.
Create ~/.ipython/profile_default/startup/00-startup.py containing lines like:
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
Set environment variables at the GUI / desktop level
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 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">
launchctl setenv PYTHONPATH /Users/myname/tmp:/Users/myname/misc
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.
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.