Computer Science Atlas
Code Review

Python 3 Examples: Import Another Python File as a Module

March 25, 2021
 

Module

In Python, a module is a single unit of Python code that can be imported (loaded and used) by other Python code. A module can contain definitions (like functions and constants), as well as statements that initialize those definitions. Once the module code is written, it can be reused by any script that imports the module.

A common way to create a Python module is to create a file with a filename that ends in .py, and write the module code in there. If we use a different file extension in the filename, or no extension at all, the standard import statements shown below will not work, and we'll have to use importlib instead, which requires more code (more info below).

To illustrate standard import usage, let's say we create a file called mymodule.py with the following function definition:

Copy
def say_hello():
   print( 'Hello, world!' )
1
2
def say_hello():
   print( 'Hello, world!' )

Now every time we want to write "Hello, world!" to the screen from a Python script, we can simply import this module rather than having to write the message again. It also allows us to change one line of code inside mymodule.py rather than in many different scripts if we ever decide to change the message we want to show in all the scripts that use this function.

Import a File in the Same Directory

Let's say we have two Python files in the same directory:

Files
Copy
myscripts/
    mymodule.py
    script.py    
myscripts/
mymodule.py
script.py

mymodule.py contains the say_hello() function we saw above.

To call say_hello() from inside script.py, we can write in script.py:

Copy
import mymodule

mymodule.say_hello()
1
2
3
import mymodule

mymodule.say_hello()

The name used in the import statement is simply the module's filename without the .py extension at the end.

Import a File in a Subdirectory (Python 3.3 and Up)

Python versions 3.3 and higher allow easy imports of modules in subdirectories of the current script's directory. If you're using a Python version lower than 3.3, you can follow the steps in Import a File in a Different Directory instead.

Let's say we move mymodule.py to a subdirectory called subdir:

Files
Copy
myscripts/
    subdir/
        mymodule.py
    script.py
myscripts/
subdir/
mymodule.py
script.py

Then if we're using Python 3.3 or higher, we can write in script.py:

Copy
import subdir.mymodule

subdir.mymodule.say_hello()
1
2
3
import subdir.mymodule

subdir.mymodule.say_hello()

In a file system path, we would separate the components of a path using / (Linux, macOS, etc.) or \ (Windows). In a Python import statement, however, we separate the path components using a dot (.).

We can also assign a shorter name for the module using an import-as statement:

Copy
import subdir.mymodule as m

m.say_hello()
1
2
3
import subdir.mymodule as m

m.say_hello()

where m is any name we choose. We can also import the function directly:

Copy
from subdir.mymodule import say_hello

say_hello()
1
2
3
from subdir.mymodule import say_hello

say_hello()

This works even if there are multiple levels of subdirectories. For example, if we had the following directory structure:

Files
Copy
myscripts/
    alpha/
        beta/
            mymodule.py
    script.py
myscripts/
alpha/
beta/
mymodule.py
script.py

we could write in script.py:

Copy
import alpha.beta.mymodule as mymodule

mymodule.say_hello()
1
2
3
import alpha.beta.mymodule as mymodule

mymodule.say_hello()

Import a File in a Different Directory

Now let's say that we move mymodule.py to a directory that is outside of the current directory tree:

Files
Copy
/
    alpha/
        beta/
            mymodule.py
    myscripts/
        script.py
/
alpha/
beta/
mymodule.py
myscripts/
script.py

By default, Python looks for files in the same directory (including subdirectories) as the current script file, as well as in other standard locations defined in sys.path. If you're curious what these locations are, you can print out the sys.path variable like this:

Copy
import sys

for p in sys.path:
    print( p )
1
2
3
4
import sys

for p in sys.path:
    print( p )

However, if the file we want to import is somewhere else entirely, we'll first have to tell Python where to look by adding search directories to sys.path. In our example, we can write in script.py:

Copy
import sys

sys.path.append( '/alpha/beta' )
import mymodule

mymodule.say_hello()
1
2
3
4
5
6
import sys

sys.path.append( '/alpha/beta' )
import mymodule

mymodule.say_hello()

Note that the path appended to sys.path is an absolute path. If we used a relative path, the path would resolve differently based on the directory from which the user is running the script, not relative to script.py's path.

To append a directory relative to this script file, you can use __file__ to get the current script's full path and build a full path to the import from there. In script.py we can write:

Copy
import os
import sys

script_dir = os.path.dirname( __file__ )
mymodule_dir = os.path.join( script_dir, '..', 'alpha', 'beta' )
sys.path.append( mymodule_dir )
import mymodule

mymodule.say_hello()
1
2
3
4
5
6
7
8
9
import os
import sys

script_dir = os.path.dirname( __file__ )
mymodule_dir = os.path.join( script_dir, '..', 'alpha', 'beta' )
sys.path.append( mymodule_dir )
import mymodule

mymodule.say_hello()

Import Any File, Including Non-.py File Extension (Python 3.4 and Up)

Absolute Path

Python versions 3.4 and higher provide functionality through the built-in importlib library that allows us to load any file anywhere as a Python module, even if the file's filename does not end in .py (it can have a different file extension, or no file extension at all).

For example, let's say we have the following directory structure:

Files
Copy
/
    alpha/
        beta/
            mymodule
    myscripts/
        script.py
/
alpha/
beta/
mymodule
myscripts/
script.py

Notice here that the mymodule filename does not have a file extension. In this case, we can't use a simple import statement to import that file. Instead, we can write in script.py:

Copy
import importlib.machinery
import importlib.util

# Import mymodule
loader = importlib.machinery.SourceFileLoader( 'mymodule', '/alpha/beta/mymodule' )
spec = importlib.util.spec_from_loader( 'mymodule', loader )
mymodule = importlib.util.module_from_spec( spec )
loader.exec_module( mymodule )

# Use mymodule
mymodule.say_hello()
1
2
3
4
5
6
7
8
9
10
11
import importlib.machinery
import importlib.util

# Import mymodule
loader = importlib.machinery.SourceFileLoader( 'mymodule', '/alpha/beta/mymodule' )
spec = importlib.util.spec_from_loader( 'mymodule', loader )
mymodule = importlib.util.module_from_spec( spec )
loader.exec_module( mymodule )

# Use mymodule
mymodule.say_hello()

Note that the path passed into SourceFileLoader() is an absolute path. If we used a relative path like ../alpha/beta/mymodule, the path would resolve differently based on the directory from which the user is running the script, not relative to script.py's path.

Relative Path

If we want to reference a file relative to our current script file's path, we can use __file__ to first get our current script file's path, and then build a full path from there:

Copy
import importlib.machinery
import importlib.util
from pathlib import Path

# Get path to mymodule
script_dir = Path( __file__ ).parent
mymodule_path = str( script_dir.joinpath( '..', 'alpha', 'beta', 'mymodule' ) )

# Import mymodule
loader = importlib.machinery.SourceFileLoader( 'mymodule', mymodule_path )
spec = importlib.util.spec_from_loader( 'mymodule', loader )
mymodule = importlib.util.module_from_spec( spec )
loader.exec_module( mymodule )

# Use mymodule
mymodule.say_hello()
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
import importlib.machinery
import importlib.util
from pathlib import Path

# Get path to mymodule
script_dir = Path( __file__ ).parent
mymodule_path = str( script_dir.joinpath( '..', 'alpha', 'beta', 'mymodule' ) )

# Import mymodule
loader = importlib.machinery.SourceFileLoader( 'mymodule', mymodule_path )
spec = importlib.util.spec_from_loader( 'mymodule', loader )
mymodule = importlib.util.module_from_spec( spec )
loader.exec_module( mymodule )

# Use mymodule
mymodule.say_hello()

References