64

Everywhere I see Python code importing modules using import sys or import mymodule

How does the interpreter find the correct file if no directory or path is provided?

ArtOfWarfare
  • 17,763
  • 14
  • 122
  • 177
Asciiom
  • 9,409
  • 7
  • 35
  • 57
  • 18
    Type `help("import")` at the console and enjoy. – DSM Mar 06 '13 at 15:58
  • 1
    http://effbot.org/zone/import-confusion.htm – Hoopdady Mar 06 '13 at 15:59
  • [`import` statement](http://docs.python.org/2/reference/simple_stmts.html#the-import-statement) – jfs Mar 06 '13 at 16:02
  • 1
    Note that everything presented here is a simplified model. The import mechanism is rather more complex, though it rarely matters for pure Python code. And since at least one version, the import machinery can be customized way more radically (for example, there's a small module which makes `import` download the latest version from Github and installs it!) which in turns makes the full story more complex. –  Mar 06 '13 at 16:22
  • 1
    @DSM - Cool! I knew the `help()` command could be used to get help on modules, classes, and functions, but I never realized that it could give you help with keywords, too! – ArtOfWarfare Jun 17 '15 at 14:57

4 Answers4

67

http://docs.python.org/3/tutorial/modules.html#the-module-search-path

6.1.2. The Module Search Path

When a module named spam is imported, the interpreter first searches for a built-in module with that name. If not found, it then searches for a file named spam.py in a list of directories given by the variable sys.path. sys.path is initialized from these locations:

  • The directory containing the input script (or the current directory when no file is specified).
  • PYTHONPATH (a list of directory names, with the same syntax as the shell variable PATH).
  • The installation-dependent default.

Note: On file systems which support symlinks, the directory containing the input script is calculated after the symlink is followed. In other words the directory containing the symlink is not added to the module search path.

After initialization, Python programs can modify sys.path. The directory containing the script being run is placed at the beginning of the search path, ahead of the standard library path. This means that scripts in that directory will be loaded instead of modules of the same name in the library directory. This is an error unless the replacement is intended. See section Standard Modules for more information.

For information on the "installation-specific default", see documentation on the site module.

Community
  • 1
  • 1
dm03514
  • 50,477
  • 16
  • 96
  • 131
  • The `site` module was the droid I was looking for. I've always wondered how a particular Python instance "knows" where things should be (aside from CWD files and whatever you append to `sys.path`. I love pulling back the curtain on things like this. Thank you! – John Carrell Nov 14 '18 at 13:26
  • I was trying this in order to cache some prerequisites within my GitHub actions, and while this answer was the correct one, I stumbled some over exactly what to set in the `PYTHONPATH` variable. In my case, I was installing the modules into `/tmp/opt` (for caching purposes) and had to set `PYTHONPATH` to `/tmp/opt/lib/python3.6/site-packages` to get things to work. – Steven W. Klassen Jan 06 '20 at 19:10
  • 1
    The actual import system has a fair bit more complexity than this section of the tutorial suggests. The answer glosses over [`sys.meta_path`](https://docs.python.org/3/glossary.html#term-meta-path-finder), which is completely customizable in Python, and this `PathFinder` behavior is usually the final stage (by default it's the last element of meta path). – wim Dec 22 '20 at 19:42
26

Also, you can see what the current path is by using the sys module

import sys
print(sys.path)
JKillian
  • 16,577
  • 8
  • 30
  • 62
reptilicus
  • 9,765
  • 5
  • 49
  • 71
9

It uses the PYTHONPATH, set as an environment variable, to find packages (folders containing __init__.py files) and modules (or, if already loaded once, retrieves the module object from sys.modules).

Fábio Diniz
  • 9,226
  • 3
  • 32
  • 42
Silas Ray
  • 24,298
  • 5
  • 44
  • 60
  • Thanks! By the way, is it in principle allowed to use absolute or relative paths? I'll accept in 10 minutes – Asciiom Mar 06 '13 at 15:59
  • You can use either, but generally, absolute are preferred for clarity of code. – Silas Ray Mar 06 '13 at 17:15
  • 1
    Not really correct. `PYTHONPATH` just augments the `sys.path`, and in most normal situations (modules imported from site-packages dirs) that env var needn't even exist. – wim May 04 '18 at 06:44
1

Python has a path variable just like the one you have inside your terminal. Python looks for modules in folders inside that path, or in the folder where your program is located.

alestanis
  • 20,205
  • 4
  • 45
  • 66