Despite our best efforts to ensure that workshop attendees configure their computers ahead of time, installation and configuration issues pop up frequently during workshops. This page collates common configuration problems encountered by instructors and presents their solutions.

Please feel free to edit this page to add new problems and solutions to the appropriate sections as you encounter them. The only requirement is that you should only add a problem once you have identified and confirmed a solution that at least worked for the cases that you encountered personally. If you encounter a problem that you don't know how to solve, please raise it in an issue in the repo so that the community can find a resolution.

Students with non-US keyboards may have difficulty finding some of the special symbols such as tilde(~), square brackets([]), curly brackets ({}), single(') and double quotes("), etc. as they may not be visibly labeled on their keyboard at all.

Go to System Preferences, Keyboard, Input Sources. You'll see a visual representation of your keyboard and what characters are available when you hold down the alt and shift keys (separately or together). These keys may have a different label depending on the language. For example the shift key may simply show a large arrow pointing up. This Apple Support page shows (barely legible) images of international keyboards. You can also check Show Input menu in menu bar and then from the menu bar you can select Show Keyboard Viewer and it will show you the labels on the various modifier keys for the selected language.

Here's an example of finding special characters on the French keyboard (AZERTY?):

You can add additional keyboard input sources for other languages if you want to see what an alternate language keyboard will look like, even if you don't have one.

If your keyboard has a Numpad (number block usually on the right hand side), you can use the 'Alt-Codes':

• press and hold down the Alt key on your keyboard
• while holding, enter a sequence of numbers on the Numpad
• your intended character should appear

Examples

If your computer has no Numpad, you can click the Windows icon, type in charmap and visually find the required font.

Please contribute Linux instructions.

Windows (Git Bash)

• None of the bash commands seem to work, although the student opened "Git Bash" and the command window is open

  • Ensure that the student has run the program mysys and not git-cmd - the latter will not open the bash emulator environment.

• Command python will not open interpreter, even though Anaconda has been installed

  • Anaconda3 now recommends users by default to NOT add anaconda path to Windows PATH environment variable. To create an alias for python, create a .bashrc file in the home directory and include this in the first line: alias python="C:/**complete path to your python.exe file in the Anaconda3 folder**"
  • For me, this looks like alias python="C:/Users/rbavery/AppData/Local/Continuum/Anaconda3/python.exe"
  • Save the .bashrc file. If a .bash_profile exits, delete or move it as it will conflict with .bashrc
  • Close and reopen GitBash. python should open the interpreter
  • Anaconda for Windows comes with its own shell [Prompt (Anaconda)] that natively supports commands like pip, conda, or python

• User has created/saved files and doesn't know where they are

  • Have users run cd after opening Git Bash and before doing anything else - this will place users in a home directory with Desktop as a subdirectory. cd then cd Desktop will place users on their Desktop.

• Copy/paste doesn't work

  • Right click the title bar and select Properties. In the Options tab, make sure QuickEdit Mode is checked. When QuickEdit mode is enabled, you can select text using the mouse cursor and right-click to copy it. To paste text, right-click when no text is selected.

• User would like to use nano

  • in git bash, run the following commands:

    curl -L -O http://www.nano-editor.org/dist/v2.2/NT/nano-2.2.6.zip
    unzip nano-2.2.6.zip -d nano-2.2.6
    echo "alias nano='winpty `pwd`/nano-2.2.6/nano'" >~/.bashrc
    

  Then quit and restart git bash.

• Git Bash appears to be installed correctly, but the terminal/cmd window isn't starting

  • It may be that the HOME environment variable is not set.

• Command-line programs with interactive prompts (e.g. python, ipython, sqlite3) hang and don't allow the user to type commands. This can arise if, when installing Git for Windows, on the installer page for Configuring the terminal emulator to use with Git Bash options, the user selects MinTTY. Adding aliases for the programs to .bash_profile can fix this (suggested at https://stackoverflow.com/questions/32597209/python-not-working-in-the-command-line-of-git-bash):

  alias python='winpty python.exe'
  alias ipython='winpty ipython.exe'
  alias sqlite3='winpty sqlite3.exe'
  

  • This problem arose under Windows 10 with Git for Windows 2.15.1.2 64-bit.

Mac (Git Bash)

• Some High Sierra (10.13.4) machines require the download of Xcode from the App Store. The download, which is available, is 5.25 GB, so this should be done prior to the lesson.

• Installing git requires that Settings < Security & Privacy < General allow an exception to install the program

All

• Command jupyter notebook fails with an error like jupyter not found.

  • It's very likely that Canopy or Anaconda did not properly append the path to its Python installation to the system path. (On Canopy, this easily occurs if students do not open GUI after installation or if they accidentally select "No" when asked if they want to make Canopy the default Python environment.) The fix is to add the right directory to the path. On a Mac using Canopy, for example, the command to do this is:

    export PATH=/Users/<username>/Library/Enthought/Canopy_64bit/User/bin:$PATH
    

• Imports of scientific Python packages fails from a command line interpreter or script (i.e., python myfile.py) even though user installed Canopy or Anaconda.

  • Use which python to make sure the Python being run is actually Anaconda or Canopy's; if not, ensure that path to Canopy or Anaconda's Python is before the system's Python in the path.
  • Ask if the user wants their path restored after the workshop and, if so, ensure this is done.

• The Jupyter notebook appears to be running but no output is shown after cells are run.

  • Ensure that ad blocker extensions are not active in the browser.
  • Turn off Windows Sophos (see https://github.com/ipython/ipython/wiki/Dev:-Windows-Sophos-issues).
  • Try jupyter notebook --ip=localhost
  • Whitelist 127.0.0.1:8888 in the firewall settings
  • If all else fails and the user has Canopy, notebooks can be opened and run directly from the Canopy GUI.

• The Jupyter kernel dies soon after starting in old OSX using Safari (see this issue)

  • Make Chrome or Firefox the default browser
  • Try jupyter notebook again from the terminal.

• The ggplot package does not get installed by conda (see this issue)

  • Try pip install -U ggplot (pip should be provided by anaconda).

  • If that fails, try:

    conda create -n py34 python=3.4 anaconda
    source activate py34
    conda install -c conda-forge ggplot
    

Windows (Anaconda)

• Anaconda apps aren't running (i.e. Jupyter).

  • Make sure Git Bash is running as administrator. To fix permanently, one has to change the settings. When searching for the program, right click on Git Bash, and select 'Properties'. On the 'Compatibility' tab, check the box titled 'Run as Administrator'.

• New users can't easily open an Jupyter notebook in an arbitrary directory.

  • The start menu shortcut created by Anaconda starts a notebook server in %USERPROFILE%\Documents\IPython Notebooks by default.
  • New users, who may be unfamiliar with the command prompt, might have trouble opening a notebook in any other directory.
  • A simple batch file with the single-line command jupyter notebook will start a notebook server in any directory from which it is run.
  • To make a batch file script that opens an Jupyter notebook in whatever directory it's run:
    1. Create a simple text file on the desktop using Right Click->New->Text Document.
    2. Re-name it "Start Jupyter Notebook Here.bat". (Don't forget to change the extension!)
    3. Open it with Notepad using Right Click->Edit.
    4. Add the text "jupyter notebook" to the file: it should look just like you would type it in a command prompt.
    5. Save and close.
  • Now when a user double clicks on the .bat file, a notebook server will spawn in that directory.
  • The user can move or copy the .bat file wherever they want their Jupyter notebook's working directory to be.
  • Instructors can distribute a copy of the file in the same folder as any example notebooks, so the users can just double-click-and-go in the correct directory without ever seeing a command-line prompt.

• matplotlib import error when non-ASCII characters are present in the user's current working directory or user name

  • See matplotlib issue 3516
  • If attendee has permission on their computer, then re-install Anaconda in another location without non-ASCII characters in the directory path e.g. C:\Local\

• Chrome reports the installation file as malicious.

  • According to the vendor, requires verification by Chrome, which is pending,
  • It is okay to ignore this warning, and the next "do you really want to harm your computer?"
  • See issue swcarpentry/workshop-template#146

• Wrong Python version runs, despite Anaconda appearing to install right version, or numpy or matplotlib won't import, despite Anaconda having them installed, or nosetests script fails with error Failed to import module nose.

  • Check with the student: do they have ArcGIS installed on the machine, and have they opened it since installing Anaconda.
  • If yes, ArcGIS has stomped all over the Python environment variables.
  • A short term solution is to
    1. Create an environment (conda create -n swc python=3)
    2. Switch to environment (activate swc). When Anaconda does this, it overwrites the Python environment variables.
    3. (First time only) Update packages in environment (conda install numpy matplotlib nose)
    4. When done, go back to default (deactivate swc). This will restore the environment variables.
  • If asked, it seems to be possible to install Anaconda so it plays nicely with ArcGIS, but is not straightforward.

• Jupyter notebook terminal window opens, then crashes with no output or explanation.

  • Check their username to see if it has a space. If so
    1. open the windows command line cmd as administrator
    2. cd to the windows system Users directory (eg. cd C:\Users)
    3. mklink /d nameWithoutSpace "name with space" replacing "name with space" with the username and nameWithoutSpace with a variant of their username with no spaces
    4. edit their jupyter notebook shortcut, changing the start in field to the link you just made, put the two arguments before %USERPROFILE% in double quotes, and replace %USERPROFILE% in the target field with the link you just made
  • This process makes a soft link (symlink) to their users directory without changing their windows username, and uses the soft link for the jupyter notebook.

• Anaconda doesn't install properly (may be due to a previous installation of python)

  • Download Python 3 from the Python website and use the default package manager pip to install Jupyter Notebook - https://jupyter.org/install.

Mac(Anaconda)

• If a ValueError about locale and UTF-8 occurs when launching Jupyter notebook, this document discusses the solution: http://conda.pydata.org/docs/troubleshooting.html#issue-valueerror-unknown-locale-utf-8-on-mac-os-x

Windows

• When trying to install a package from RStudio, an error returns saying it is not available.

The issue is that when trying to install a package (specifically dplyr) from RStudio, install.packages("dplyr") returns an error saying that the package is not available for this version of R.

This was happening on a brand new installation of R and RStudio from the links in the workshop page.

The problem seems to be that there was an older version of R installed in the computer and RStudio was picking this one up by default, instead of the newer. (You can check this with sessionInfo()).

Forcing RStudio to run the newer version of R fixed the problem. This post explains how to switch between R versions on RStudio and different operating systems.

Mac

Installing dplyr might require a complier. If the learner hasn't installed the xcode command line tools the installation will fail. This can be fixed by opening a terminal window and typing xcode-select --install.

All

• When pushing to GitHub, the username or password is rejected although student knows that they are correct.
  • Some students have needed to use their full email address, rather than their username, in the username field.
  • (Although this makes little sense) Try hitting backspace many times in the password field to "clear out old password info". This might be a Git Bash issue, but is unconfirmed.

Windows (Git Bash)

• The user is prompted to enter email address on first commit.

  • Appears to be a bug in Git 1.8.4, as the user is prompted even if the email address is set in her global configuration. This should only occur on first commit.

• git push to a GitHub repo fails with the error could not read Username for https:...: No such device or address.

  • This is a bug in Git Bash 1.8.5 - have users install 1.8.4.
  • If Git Bash 1.8.5 has been installed, using SSH instead of HTTPS for the push is a workaround, but takes several minutes to set up. First generate and set up the SSH key. After generating the SSH key and setting up GitHub to use it, change the origin from the Git repository directory using commands like these (with the appropriate user name and repository name):
    • git remote rm origin
    • git remote add origin git@github.com:username/repo.git

• git push to BitBucket using git@bitbucket.org:USER/REPOSITORY gives Permission denied (publickey). fatal: Could not read from remote repository.

  • This can happen if a user has set up BitBucket to use SSH keys but the SSH keys are not present on the machine they are using for the workshop (e.g. they have the SSH keys on their desktop but not their laptop).
  • A workaround is to use https://bitbucket.org/USER/REPOSITORY and they will be prompted for their username and password.
  • A similar issue can impact GitHub users - instructions to manually generate SSH keys are located at https://gist.github.com/adamjohnson/5682757

• Configuring the git editor to a Windows program like Notepad++.exe is not intuitive. If the path to the program is not in the PATH, changing the system environment variable may require a restart. Additionally, the editor program may open with the previous session and tabs, causing the commit to abort. The following setup works for Notepad++ (adjust for the correct install path for 32-bit / 64-bit executable):

  git config --global core.editor "'C:/Program Files/Notepad++/notepad++.exe' -multiInst -notabbar -nosession -noPlugin"
  

• nano is not installed.

  • Ensure that the Software Carpentry installer has run. Try re-executing the installer.

• nano has been installed but calling nano returns command not found

  • Find the folder holding nano.exe on your computer
  • Edit .bash_profile and add

export PATH=/c/path-to-nano.exe-folder:$PATH

• calling nano from the shell doesn't work and returns 'Redirection is not supported'

  • Reinstall Git Bash, and during the install process, be sure to Select "Use Windows' default console window" (which is not the default option)

• The Git Bash window does not open to full screen.

  • One has to change the settings. When searching for the program, right click on Git Bash, and select 'Properties'. On the 'Layout' tab, change the size to roughly 237x69.

Windows (Rstudio):

• The Git tab does not appear in Rstudio.
  • You need to tell Rstudio where to find your git executable. Assuming you are using Git Bash:
    • Go to Tools->Global options.
    • Select Git/SVN.
    • Under Git executable select Browse.
    • Navigate to and select following file: C:/Program Files (x64)/git/bin/git.
  • Restart Rstudio. See also this screenshot.

Mac

• Running the git command fails with an error like Illegal operation.

  • It appears that git 1.9.x is incompatible with Mac OS X 10.6 and 10.7. Version 1.8.4.2 works for Mac OS X 10.6.8 (newest release of Snow Leopard). Other older installers are available from http://sourceforge.net/projects/git-osx-installer/files/ or https://code.google.com/archive/p/git-osx-installer/downloads.

• Running git on Mac OS X 10.8.5 produced an error message reporting "lazy symbol binding failed".

  • Most online advice involved installing XCode with the command line tools, which is a 1.6 GByte download...
  • Note that as April 2015, XCode for Mac OS X 10.8.5 is no longer available from the App Store, so you'll need to get an older version from the Apple Developer website. For that you'll need a Developer account with Apple (so probably an instructor should do download this in advance and keep it in a USB stick).
  • The Snow Leopard images from the git-osx-installer project work too, and don't require an XCode download.
  • Some High Sierra (10.13.4) machines require the download of Xcode from the App Store. The download, which is available, is 5.25 GB, so this should be done prior to the lesson.

• Trying to clone a repository from github fails with an error like error: SSL certificate problem, verify that the CA cert is OK

  • A temporary fix that should allow the learner to progress with the lesson is to run

    export GIT_SSL_NO_VERIFY=true`
    

  • This setting change will not persist after rebooting the machine. The error is probably caused by expired SSL certificates and should be fixed by updating the OS.

  • If an OS update is not possible, you can also try installing the tigerbrew port of git, like so:

    ruby -e "$(curl -fsSkL raw.github.com/mistydemeo/tigerbrew/go/install)"
    export PATH=/usr/local/sbin:/usr/local/bin:$PATH
    brew install git
    hash -r
    git clone ...
    

Linux

• The recommend configuration for gedit doesn't work.

  • Check gedit's version with gedit --version and update it to 3.x.

• Permission denied (public key) on pushing to Github.

  • This has several causes and thus several solutions: GitHub has a list. In a nutshell:
    • Don't use sudo (and check whether the permissions for SSH keys are correct).
    • Connection problems or weird routing problems: ssh -vT git@github.com should print github.com and port 22.
    • Connect only as user git .
    • Check whether ssh-add -l prints a key, if not, create one.
    • Check whether ssh-keygen -lf ~/.ssh/id_rsa.pub prints several keys, and check which one GitHub uses in the account settings.
    • You can always troubleshoot more using ssh -vT git@github.com.

• Error 403 returned on a git push to GitHub.

  • This is usually caused by an older version of Git. GitHub now requires git 1.7.10 or later.

• A git push results in a dialog requiring a password to unlock the private key: "Enter password to unlock the private key. An application wants access to the private key xxxxx".

  • This can be caused by an SSH agent, such as Gnome Keyring, managing SSH keys when these are already managed with OpenSSH. Disable SSH keyring support in Gnome.

Mac

• Issue with sqlite3 and no readline support on the macs. That is, up arrow will not return the last command typed. This can be fixed, but requires installing sqlite3 from source: sqlite3 ships without readline support.

Windows (Git Bash)

This problem arose on Git Bash git version 1.9.4.msysgit.1 and make GNU Make 3.81 on Windows 7 SP 1.

Using a wildcard in an action can throw an exception e.g. given Makefile:

all :
        touch sample1.txt
        touch sample2.txt

clean : 
        rm -f *.txt

$ make all
touch sample1.txt
touch sample2.txt
$ make clean
c:\Users\mjj\.swc\lib\make\bin\make.exe: Interrupt/Exception caught (code = 0xc00000fd, addr = 0x4227d3)

One fix is to use Make's $(wildcard ...) function e.g.

clean : 
        rm -f $(wildcard sample*.txt)

$ make clean
rm -f sample1.txt sample2.txt

Another solution is to add the following at the start of the Makefile:

SHELL=C:/Windows/System32/cmd.exe

However, the former is preferable as it uses Make's own functions and does not lead to an unportable Makefile.

Windows (Git Bash)

This problem arose on Git Bash git version 1.9.4.msysgit.1 and make GNU Make 3.81 on Windows 7 SP 1.

Using > in a Makefile can also cause the above exception, in which case the solution is to use the SHELL assignment as above.

Debian (unknown version)

If $(wildcard ...) throws a SegmentationFault then use the contents of the expression e.g. replace:

rm -f $(wildcard *.dat)

with

rm -f *.dat

For variable assignments e.g.

TXT_FILES= $(wildcard books/*.txt)

use shell and find e.g.

TXT_FILES=$(shell find books -name "*.txt")

Windows

If Open Refine closes immediately after opening, use the command prompt to navigate to the openrefine directory. Type refine to run the refine.bat script - this will give you error messages you can look at.

OpenRefine requires Java JRE to be installed. You can install it from here

Sometimes the environment variable for Java gets unset if an installation gets messed up. To fix, open windows explorer and right click on My Computer. Under the advanced tab click on Environment variables. Add an environment variable called JAVA_HOME and navigate to where java is installed (usually \Program Files\Java\jdkx.y.z)