'import site' failed; use -v for traceback

If you suddenly start seeing this error every time you try to run Python:

'import site' failed; use -v for traceback

Chances are you have an erroneous file in your site-packages directory that's screwing up Python's import path initialisation and could lead to you being unable to import some installed modules.

To figure out which file this is you can use the Python debugger, pdb:

> python -v
>>> import pdb
>>> pdb.pm()
> [python_lib_path]/posixpath.py(173)exists()
-> return False
(Pdb) u
> [python_lib_path]site.py(146)addpackage()
-> f.close()
(Pdb) f
<closed file '[site-packages]._blah.pth', mode 'rU' at 0x52c38>

Your actual output will be quite a bit different with a lot of debugging information spewed into the console but let's explain what's going on here:

1. Run Python in verbose mode to get a traceback.
2. import pdb
3. Run the pm (postmortem) function to enter the (Pdb) shell and inspect the exact point at which the error occured.
4. Go up a level in the stack with u.
5. Inspect the f file object.

This tells us that ._blah.pth is causing Python's site import routine to choke. [bug report]

Move this file out of site-packages and try again, repeating the steps above if you get the same error.

When you run Python, it runs through all the directories specified by your PYTHONPATH environment variable, looking for .pth files. These can contain further directories to be added to the import path and are typically created by python packaging systems like easy_install. [more info on .pth files]

So what's up with this one?

The so called "dot-underscore" or AppleDouble files are actually created by Mac OS X. They contain resource forks and extra file metada for their corresponding file (the example we found earlier contains metadata for a legitimate file blah.pth).

Mac filesystems like HFS+ support resource forks natively and don't need these files, so they aren't usually created when you're accessing your machine locally. They can get created when you're accessing it over a network using the Samba protocol or if the connecting Mac otherwise thinks you don't support resource forks—usually if you're on Windows or an NFS filesystem.

You can safely delete these files from the site-packages directory and Python should be back to normal.