Skip to main content

How to Resolve "ModuleNotFoundError: No module named 'discord'" in Python

discord.py is a popular Python library for interacting with the Discord API

This guide explains to install discord.py in various environments: Windows, macOS, Linux, Visual Studio Code, PyCharm, Anaconda, and Jupyter Notebook. We'll cover basic installation, voice support, troubleshooting common installation problems, and how to resolve the dreaded "ModuleNotFoundError: No module named 'discord'".

Basic Installation (All Platforms)​

The standard way to install discord.py is using pip, Python's package installer. Open your terminal (Command Prompt or PowerShell on Windows, Terminal on macOS/Linux) and run one of the following commands:

pip install discord.py              # For most users (Python 2 or virtual environments)
pip3 install discord.py             # For Python 3 (might be pip3.10, pip3.11, etc.)
python -m pip install discord.py    # If 'pip' isn't in your PATH
python3 -m pip install discord.py   # For Python 3, if 'pip3' isn't in your PATH
py -m pip install discord.py        # Windows 'py' launcher

Choose the command that works for your system. If one fails, try the next. The python -m pip (or python3 -m pip, py -m pip) form is generally the most reliable, as it uses the specific Python interpreter you're intending to use.

Voice Support (Optional)​

If you need voice support (audio sending/receiving), install with the [voice] extra:

pip install "discord.py[voice]"

# OR, adapt as above for pip3, python -m pip, etc.

Linux Prerequisites​

On Linux, voice support requires additional system libraries:

sudo apt update  # Important: Update package lists first
sudo apt install libffi-dev libnacl-dev python3-dev

Troubleshooting Installation Issues​

'pip' is not recognized​

If you get an error saying pip is not recognized, try the following:

  • Use python -m pip (or python3 -m pip, py -m pip) as shown above. This uses the Python interpreter directly to run pip.
  • Ensure Python and pip are correctly installed and added to your system's PATH environment variable. This is a common setup issue, particularly on Windows.

Permissions Errors​

If you get a "Permission denied" error, you might need to:

  • Linux/macOS: Use sudo (use with caution!): 
    sudo pip3 install discord.py
  • All Platforms: Install into your user directory (recommended): 
    pip install discord.py --user
    This installs the package for your user account only, avoiding system-wide permission issues.

Virtual Environments​

It's highly recommended to use virtual environments for Python projects. This isolates project dependencies and prevents conflicts. Here's how to create and use a virtual environment:

# Create the environment (choose ONE of these)
python3 -m venv venv  # Recommended: Uses the built-in 'venv' module
python -m venv venv   # For older Python 3 versions
py -m venv venv       # Windows 'py' launcher

# Activate the environment (different commands for different shells)
# Linux/macOS (bash/zsh):
source venv/bin/activate

# Windows (Command Prompt):
venv\Scripts\activate.bat

# Windows (PowerShell):
venv\Scripts\Activate.ps1

# Now install discord.py *inside* the activated environment:
pip install discord.py

Important: Always activate your virtual environment before installing packages. If you're using an IDE (like VS Code or PyCharm), configure it to use the virtual environment's interpreter.

Troubleshooting ModuleNotFoundError: No module named 'discord'​

Even after installing discord.py, you might still encounter the ModuleNotFoundError: No module named 'discord' error. This usually indicates one of the following problems:

  • Incorrect Interpreter/Environment: You've installed discord.py in one Python environment (e.g., a virtual environment, or a specific Python version), but your script is running with a different interpreter that doesn't have access to that installation. This is extremely common.
  • Typos: Double-check the import statement. It should be import discord. A misspelling (e.g., import dicord) will cause this error.
  • Shadowing: (Less common, but possible) You might have a file or directory named discord in your project, which is preventing Python from finding the installed discord module.
  • Package not installed: It's possible that the installation process was not successful.

Solutions:

  1. Verify Installation:

    First, confirm that discord.py is actually installed in the environment you think it is. Activate your virtual environment (if you're using one), and then run:

    pip show discord.py
    # OR
    python -m pip show discord.py

    This will show you information about the installed package, including its location. If it says "Package(s) not found", then the installation didn't work, or you're in the wrong environment.

  2. Check Your Interpreter (IDE/Terminal):

    • IDE (VS Code, PyCharm, etc.): Make absolutely sure your IDE is configured to use the correct Python interpreter – the one associated with the environment where you installed discord.py. In VS Code, use the Python: Select Interpreter command. In PyCharm, check your project's interpreter settings. This is the most frequent cause of ModuleNotFoundError after a successful installation.
    • Terminal: If running from the terminal, activate your virtual environment before running the script. If you're not using a virtual environment, be certain you're using the same Python interpreter you used for installation (e.g., python3 vs. python).

  3. Rename Conflicting Files/Directories:

    If you have a file or directory named discord in your project, rename it. This is shadowing the installed module.

  4. Restart IDE/Kernel:

    Sometimes, IDEs or Jupyter kernels need a restart to recognize newly installed packages. Try restarting your IDE or kernel.

  5. Reinstall (as a last resort):

    If all else fails, try uninstalling and reinstalling discord.py:

    pip uninstall discord.py
    pip install discord.py
    # (or pip3, python -m pip, etc., as appropriate)

    This can sometimes fix corrupted installations.

Installation in Specific IDEs/Environments​

Visual Studio Code​

  1. Open the Command Palette: Ctrl+Shift+P (Windows/Linux) or Cmd+Shift+P (macOS).
  2. Type "Python: Select Interpreter" and choose the appropriate interpreter (ideally, the one associated with your virtual environment).
  3. Open a new terminal within VS Code (Ctrl+ ` or View -> Terminal).
  4. Run pip install discord.py (or the appropriate variant) in the VS Code terminal.

PyCharm​

  1. Go to File > Settings (or PyCharm > Preferences on macOS).
  2. Navigate to Project: <your_project_name> > Python Interpreter.
  3. Click the "+" button to add a package.
  4. Search for discord.py and click "Install Package".

Anaconda​

Use the conda package manager:

conda install -c conda-forge discord.py

Jupyter Notebook​

Run the following command in a notebook cell:

!pip install discord.py

Conclusion​

This guide provided detailed steps for installing the discord.py module, as well as solutions for the ModuleNotFoundError: No module named discord error, covering the most common causes.

The error is almost always caused by installation issues, incorrect interpreter, or name shadowing.

If you encounter the error, make sure you have installed the right package, verify the installation, check the interpreter and check for naming conflicts.

Table of Contents