sys.path Explained

sys.path is one of the most useful things to understand when Python imports are confusing.

It tells Python where to look for modules and packages when you use import. If an import fails, or Python imports the wrong file, sys.path often explains why.

This page shows:

what sys.path is
what it usually contains
how Python uses it during import
how to inspect it safely
when changing it helps, and when it causes more problems

Quick way to inspect `sys.path`

Use this to see where Python is looking for modules:

import sys

for folder in sys.path:
    print(folder)

This is helpful when an import does not work as expected.

What `sys.path` is

sys.path is a list of folder paths stored in the sys module.

Important points:

sys.path is a list
Python checks these folders when you use import
Each item is usually a string containing a path
It belongs to the sys module

Example:

import sys

print(type(sys.path))
print(sys.path[:3])

Possible output:

<class 'list'>
['/my-project', '/usr/lib/python3.12', '/usr/lib/python3.12/site-packages']

This means Python will search those locations for modules.

If you are new to imports, see how import works in Python and Python modules explained.

Why `sys.path` matters

sys.path matters because it explains where Python searches for modules.

That helps you understand problems like these:

one file imports correctly, but another does not
you get ModuleNotFoundError
Python imports the wrong file
code works on one computer but not another

If you are fixing an import error, sys.path is often one of the first things to check. It is especially useful for debugging ModuleNotFoundError and other import problems.

How Python uses `sys.path` during import

When you write an import like this:

import mymodule

Python checks the folders in sys.path from first to last.

Important rules:

Python searches in order
earlier paths have higher priority
if two modules have the same name, the first match is used
the search order affects which file gets imported

Example idea:

Folder A contains mymodule.py
Folder B also contains mymodule.py
If Folder A appears earlier in sys.path, Python imports that one

You can verify which file was imported like this:

import mymodule

print(mymodule.__file__)

This is a very useful check when Python seems to import the wrong module.

For a beginner-friendly import overview, see how to import a module in Python.

What you usually find inside `sys.path`

The exact contents are different on each computer, but sys.path often includes:

the current script folder or working location
standard library folders
site-packages folders for installed packages
extra paths added by environment variables, tools, or project settings

For example, you might see paths like:

your project folder
a Python installation folder
a virtual environment folder
a site-packages folder

Because of this, sys.path is not the same on every computer. It depends on:

your operating system
your Python version
your virtual environment
how you run the script

How to view `sys.path`

First import sys, then print sys.path.

Print the whole list

import sys

print(sys.path)

This works, but the output can be hard to read.

Print one path per line

import sys

for path in sys.path:
    print(path)

This is usually easier to inspect.

Check whether a folder is included

import sys

target = "/my-project"
print(target in sys.path)

If the folder you expect is missing, Python may not be able to import your module from that location.

Temporary changes to `sys.path`

You can change sys.path while your program is running.

Add a path to the end

import sys

sys.path.append("/my-project")
print(sys.path[-1])

This adds the folder at the end of the search list.

Add a path to the beginning

import sys

sys.path.insert(0, "/my-project")
print(sys.path[0])

This gives that folder higher priority during import.

Important note

These changes are temporary.

They only last while the program runs. When the script ends, the changes are gone.

This can be useful for quick testing, but it is usually not the best long-term solution.

When changing `sys.path` is a bad idea

Editing sys.path can solve a problem quickly, but it often creates new ones.

Common downsides:

it can hide project structure problems
it can make code harder to understand
it may behave differently on another computer
it can cause the wrong module to be imported

For example, this kind of code may work on your machine:

import sys
sys.path.insert(0, "/Users/alex/Desktop/project")

But it may fail on someone else's computer because that folder does not exist there.

For beginners, it is usually better to fix the root cause instead of adding paths manually.

Better fixes than editing `sys.path`

In many cases, these are better solutions:

run the script from the correct project folder
use a proper package structure
use virtual environments for installed packages
check that the module name and file name are correct

If a package is installed in the wrong environment, creating and using a virtual environment is often the real fix. See how to create and use a virtual environment in Python.

Common import problems linked to `sys.path`

Here are common reasons imports fail or behave strangely.

The needed folder is not in `sys.path`

If Python never searches the folder that contains your module, the import will fail.

You are running Python from a different folder than expected

The folder you run from can affect imports. A script may work in one location and fail in another.

A local file has the same name as a standard library or installed module

For example, if you create a file named random.py, it may interfere with Python's standard random module.

This can make Python import your file instead of the one you expected.

The package is installed in a different Python environment

You may have installed a package in one interpreter, but be running another interpreter.

That is why these two checks are so useful:

import sys
print(sys.executable)

and:

import some_module
print(some_module.__file__)

Simple debugging checklist

When imports are not working, try these steps.

1. Print `sys.path`

import sys

for path in sys.path:
    print(path)

2. Print the current working directory

import os

print(os.getcwd())

3. Check which Python interpreter is running

import sys

print(sys.executable)

4. Check the exact module file being imported

import module_name

print(module_name.__file__)

This is often enough to find the real problem.

You can also run these checks directly from the command line:

python -c "import sys; print(sys.path)"
python -c "import os; print(os.getcwd())"
python -c "import sys; print(sys.executable)"
python -c "import module_name; print(module_name.__file__)"

If you want a broader troubleshooting process, see how to debug Python code.

Common mistakes

These problems are often connected to sys.path:

running a script from the wrong folder
using a different Python interpreter than the one where the package was installed
creating a file with the same name as a module you want to import
adding paths manually and forgetting that import order matters
expecting sys.path changes to remain after the script ends

FAQ

What is the difference between `sys.path` and `PATH`?

sys.path is used by Python to find modules.

PATH is an operating system environment variable used to find programs and commands.

They are different things.