How to Solve "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
(orpython3 -m pip
,py -m pip
) as shown above. This uses the Python interpreter directly to runpip
. - 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):
This installs the package for your user account only, avoiding system-wide permission issues.
pip install discord.py --user
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 installeddiscord
module. - Package not installed: It's possible that the installation process was not successful.
Solutions:
-
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.pyThis 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.
-
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 thePython: Select Interpreter
command. In PyCharm, check your project's interpreter settings. This is the most frequent cause ofModuleNotFoundError
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
).
- 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
-
Rename Conflicting Files/Directories:
If you have a file or directory named
discord
in your project, rename it. This is shadowing the installed module. -
Restart IDE/Kernel:
Sometimes, IDEs or Jupyter kernels need a restart to recognize newly installed packages. Try restarting your IDE or kernel.
-
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
- Open the Command Palette:
Ctrl+Shift+P
(Windows/Linux) orCmd+Shift+P
(macOS). - Type "Python: Select Interpreter" and choose the appropriate interpreter (ideally, the one associated with your virtual environment).
- Open a new terminal within VS Code (
Ctrl+
` or View -> Terminal). - Run
pip install discord.py
(or the appropriate variant) in the VS Code terminal.
PyCharm
- Go to
File > Settings
(orPyCharm > Preferences
on macOS). - Navigate to
Project: <your_project_name> > Python Interpreter
. - Click the "+" button to add a package.
- 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.