Canopy GUI setup requires extra steps when user's home path contains non-ASCII characters

If your user name, and hence your home directory name, are all ASCII (i.e. English letters and numbers), then this article will not help you.

If they do contain non-ASCII characters, then the simplest workaround is to log in as a user with an ASCII user name, and then do a normal installation. Note that if you do this, then you will only be able to use Canopy when you are logged in as that user.

Otherwise, you must take several extra steps during installation and setup.

1) On Windows, you must "Install for all users", which requires administrative access.

If the installer offers you the option to "Install for all users" after you accept the license, then select it, complete the installation normally, and skip to step (2) below.

Otherwise, you must cancel the installation, then follow these preliminary steps exactly (even if you are already an administrator):

  • Type "cmd" in the Start Menu's search box.
  • Right-click on the "cmd" program which appears at the top of the start menu and select "Run as Administrator".
  • If you are not already an administrator, enter the password for an administrative user when asked.
  • A command prompt (DOS-like) window will open. At the command prompt, type: 
    msiexec /i c:\<path-to-canopy-installer-file>.msi
    (be sure to type the actual filename, including full path, of the downloaded installer file), and press the Enter key.

The installer will start, and you should now be able to select the "Install for all users" option when offered it after you accept the license.

2) On Windows, OS X, and Linux, before your first startup, you should specify a different path for your Canopy configuration directory.

Before running Canopy the first time (and always), set the environment variable "CANOPY_CONFIG" to a directory whose path contains only ASCII characters and that you are authorized to write to. For help in setting environment variables see "How do I set PYTHONPATH and other environment variables for Canopy?".

3) On Windows, OS X, and Linux, during your first startup, you must specify a different path for your Canopy environment.

(Background information: this step is necessary because even if you change the directory of the base Canopy Python installation to a directory which is not on your home path (step 1), the Canopy GUI itself, and the User Python environment, are installed by default into your home path.)

Choose a directory which will be the root for your Canopy Python environment management. The path to this directory must contain only ASCII characters (i.e. it cannot be inside your home directory) and it must be one that you are authorized to write to. If you have difficulty finding such a directory, you may want to get help from a geek friend to locate or create a suitable directory on your computer.

Canopy version 1

The first time that you start Canopy, you will be asked to specify the above environment directory.

Canopy version 2

Before starting Canopy, use a text editor to create a text file, preferences.ini, in the Canopy configuration directory specified in step 2 above. Include the following lines in this file, substituting the environment root directory that you chose, and the configuration directory that you chose in step 2.

user_install_dir = Full-path-to-environment-root-directory
user_data_dir = Full-path-to-configuration-directory

Then start Canopy.


Have more questions? Submit a request


  • Avatar
    Jose Eduardo Castanho

    Great help!, But warning this trick before the setup could have saved me a lot of time.

  • Avatar
    Jonathan March

    @Jose thanks for the feedback -- we will try to do better with this!

  • Avatar
    Fanzhi Zeng

    @Jonathan March i have set up my Canopy environment in default,now i want to change it,what should i do.

  • Avatar
    Jonathan March

    @Fanzhi - do a full reset as described here:

    Uninstall / reinstall is not needed, but if you are not already using the current version (1.5.2), then this would be a good opportunity to update. See

  • Avatar
    Xavier Soria Poma

    Sorry, is there any problem now or in the future?, I did not use your recommendation "C:\Program Files\Canopy" Instead, I used D:\canopy32

    Thanks a lot.

  • Avatar
    Mihalis Mavridis

    My Greek name created a lot of troubles. But this solution has worked for me very well. Thanks a lot!!!

Powered by Zendesk