How to Resolve Python "ModuleNotFoundError: No module named 'exceptions'/'python-docx'"

Encountering a ModuleNotFoundError in Python means the interpreter cannot find the module specified in your import statement. This guide addresses two specific errors: ModuleNotFoundError: No module named 'exceptions' (related to Python 2 vs. Python 3 changes) and ModuleNotFoundError: No module named 'python-docx'.

We will explain the distinct causes and provide the correct solutions for each error.

Error 1: ModuleNotFoundError: No module named 'exceptions'

Cause: Python 2 Module in Python 3 Code

This error occurs almost exclusively when you run code originally written for Python 2 within a Python 3 environment. In Python 2, common exception classes (like ValueError, TypeError, ImportError) were often accessed via a dedicated exceptions module (e.g., import exceptions; raise exceptions.ValueError(...)).

In Python 3, this exceptions module was removed, and all standard exception classes became built-in, you can access them directly without any import.

# Error Scenario (running this in Python 3)
try:
    # ⛔️ Attempting to import the non-existent Python 2 module
    import exceptions
    # Code that might try to use exceptions.ValueError, etc.
    print("Successfully imported exceptions module (unexpected in Py3)")
except ModuleNotFoundError as e:
    # ⛔️ ModuleNotFoundError: No module named 'exceptions'
    print(f"Caught expected error: {e}")

Solution: Remove import exceptions; Use Built-in Exceptions

The fix is to update the code for Python 3:

1. Remove any lines that say import exceptions.
2. Refer to standard exceptions directly by their names (they are built-in).

# ✅ Corrected Code for Python 3

try:
    # No need to import exceptions
    num = int("abc") # This will raise a built-in ValueError
except ValueError as e: # ✅ Use ValueError directly
    print(f"Caught expected built-in ValueError: {e}")
except Exception as e:
     print(f"Caught other exception: {e}")

# Example raising an exception
# raise TypeError("This is a built-in TypeError") # ✅ Use directly

Simply remove the outdated import and use the standard exception names available globally in Python 3.

Error 2: ModuleNotFoundError: No module named 'python-docx'

This error indicates Python cannot find the installed python-docx library, which is used for creating and updating Microsoft Word (.docx) files.

Cause: python-docx Library Not Installed or Found

The primary reason is that the python-docx package is not installed in the specific Python environment (e.g., the global environment or the active virtual environment) that is running your script.

# Error Scenario: python-docx not installed or not found in environment
try:
    # ⛔️ ModuleNotFoundError: No module named 'docx' (or sometimes 'python-docx' depending on import style)
    # The common import name is usually 'docx' after installation
    import docx
    print("Successfully imported docx (requires installation)")
except ModuleNotFoundError as e:
    print(f"Caught expected error: {e}")

note

Although you install python-docx, you often import it as docx

Common Installation/Environment Issues

• Package simply not installed.
• Package installed in a different Python environment (e.g., global Python vs. a project's virtual environment).
• Virtual environment exists but was not activated before running the script or installing packages.
• IDE (VS Code, PyCharm) is configured to use the wrong Python interpreter.
• Filename shadowing (you named a file docx.py or python-docx.py).

Solution 1: Install the python-docx Package (pip/conda)

Ensure the package is installed in your active environment. Open your terminal/command prompt, activate your virtual environment if necessary, and run:

• Using pip:

  pip install python-docx
  
  # Or: 
  pip3 install python-docx
  # Or: 
  python -m pip install python-docx
  # Or: 
  py -m pip install python-docx (Windows)
  note

  Use --user or sudo only if not using a virtual environment and facing permission issues

• Using conda:

  conda install -c conda-forge python-docx

Solution 2: Verify the Python Environment (Virtual Env, IDE)

• Virtual Environments: ALWAYS activate your virtual environment (source venv/bin/activate, venv\Scripts\activate.bat, etc.) before installing packages or running your script. Ensure consistency.
• IDE Configuration: Double-check that your IDE (VS Code: "Python: Select Interpreter"; PyCharm: "Settings" -> "Project" -> "Python Interpreter") is configured to use the same Python interpreter (especially the one inside your virtual environment) where you installed python-docx.

Solution 3: Check for Filename/Variable Shadowing

• Make sure you don't have a file named docx.py or python-docx.py in your project that could interfere with the import. Rename your file if needed.
• Avoid using docx or python-docx as variable names before importing.

Debugging Steps (pip show, Restart, Reinstall)

• Verify Installation: In your activated environment's terminal, run pip show python-docx. If it's not found, it's not installed there. If found, check the Location:.
• Restart: Close and reopen your IDE, terminal, or Jupyter kernel.
• Reinstall/Upgrade:

  pip uninstall python-docx
  pip install python-docx
  # Or upgrade:
  # pip install --upgrade python-docx

Conclusion

The ModuleNotFoundError requires different solutions based on the specific module name:

• No module named 'exceptions': This indicates Python 2 code running on Python 3. Solution: Remove import exceptions and use Python 3's built-in exception names (e.g., ValueError, TypeError).
• No module named 'python-docx': This means the third-party python-docx library is missing from the active Python environment. Solution: Install it using pip install python-docx (or conda install ...) within the correct activated virtual environment and ensure your IDE is configured to use that same environment.

Always check your Python version context for the exceptions error and your package installation environment for the python-docx error.