How to Solve "ModuleNotFoundError: No module named 'keyboard'" in Python

The ModuleNotFoundError: No module named 'keyboard' error in Python means that the keyboard library, which provides functions for controlling and monitoring keyboard input, is not installed in your Python environment.

This guide provides a complete explanation for solving this error, covering:

• Correct installation using pip.
• Troubleshooting common installation problems.
• Installation within specific environments (virtual environments, VS Code, PyCharm, Anaconda, Jupyter Notebook).
• Avoiding common pitfalls like naming conflicts.

Understanding the Error

The ModuleNotFoundError is a very common error. It simply means that when your Python code tries to import keyboard, the Python interpreter can not find a module with that name. This almost always means the package isn't installed, or isn't installed where Python is looking.

Basic Installation with pip

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

pip install keyboard            # Usually for Python 2 or within a virtual environment
pip3 install keyboard           # Usually for Python 3 systems
python -m pip install keyboard  # Use if 'pip' isn't directly accessible
python3 -m pip install keyboard # Use for Python 3 if pip3 isn't recognized.
py -m pip install keyboard      # Use py alias for python executable (Windows specific)

Try each of these commands one by one until one works. The python -m pip (or python3 -m pip) form is often the most reliable because it uses the specific Python interpreter you intend.

Troubleshooting Installation

If the installation fails, or if you still get the ModuleNotFoundError after installing, consider these common issues:

Permissions Errors

On Linux or macOS, you might need sudo to install packages globally:

sudo pip3 install keyboard  # Use with CAUTION

A much better alternative (and highly recommended!) is to install packages for your user only, which doesn't require sudo:

pip install keyboard --user

pip Not Found / Not in PATH

If you get an error like 'pip' is not recognized, try these:

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

Virtual Environments (Essential!)

Always use virtual environments for your Python projects. This isolates project dependencies and avoids conflicts.

1. Create a virtual environment:

   python3 -m venv venv  # Recommended: Use the built-in 'venv' module
   # OR (if the above fails)
   python -m venv venv
   # OR (Windows)
   py -m venv venv

2. Activate the environment:

   • Linux/macOS (bash/zsh):

     source venv/bin/activate

   • Windows (Command Prompt):

     venv\Scripts\activate.bat

   • Windows (PowerShell):

     venv\Scripts\Activate.ps1

     If you see a "running scripts is disabled" error in PowerShell, run this command once (as an administrator, if necessary) and then try activating again:

     Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

3. Install keyboard inside the activated environment:

   pip install keyboard

Naming Conflicts (Shadowing)

Do not name any of your Python files keyboard.py. This will "shadow" the installed keyboard module, preventing Python from finding the real package. If you have a keyboard.py file in your project directory, rename it!

Similarly, do not create a variable named keyboard in the global scope, as this will also shadow the module after you import it.

IDE Interpreter Configuration (VS Code, PyCharm)

If you're using an IDE like VS Code or PyCharm, you must configure it to use the correct Python interpreter:

• VS Code:

  1. Open the Command Palette: Ctrl+Shift+P (Windows/Linux) or Cmd+Shift+P (macOS).
  2. Type "Python: Select Interpreter".
  3. Choose the interpreter associated with your virtual environment (if you're using one) or the correct system-wide Python installation.

• PyCharm:

  1. Go to File > Settings (or PyCharm > Preferences on macOS).
  2. Navigate to Project: <your_project_name> > Python Interpreter.
  3. Select the correct interpreter from the dropdown, or configure a new one if needed.

Reinstalling the Package

Try to uninstall, and then install the package again, in case some files were not installed correctly the first time:

pip uninstall keyboard
pip install keyboard

Installation in Specific Environments

Anaconda

conda install -c conda-forge keyboard

Jupyter Notebook

!pip install keyboard

Using the keyboard module (Basic Example)

Once installed correctly, here's a very basic example of using the keyboard module:

import keyboard

# Wait for the 'space' key to be pressed:
keyboard.wait('space')
print("Spacebar pressed!")

# Record key presses until 'esc' is pressed:
events = keyboard.record(until='esc')
print("Recorded events:", events)

# Play back the recorded events:
# keyboard.play(events) # This often requires root/admin privileges

# Block a key (requires root/admin)
# keyboard.block_key('a')

# Check if a key is pressed
if keyboard.is_pressed('ctrl+c'):
    print('Ctrl+C is pressed')

Important: Many features of the keyboard module (like blocking keys, global hotkeys, and sometimes even keyboard.play()) require administrator/root privileges to function correctly. This is because they need low-level access to the operating system's input handling.

Conclusion

The ModuleNotFoundError: No module named 'keyboard' error is almost always due to a simple installation or environment issue.

By following the steps in this guide, you should be able to install the keyboard module correctly and start using it in your Python projects. Always use virtual environments, double-check your IDE's interpreter settings, and be aware of the security implications (and privilege requirements) of using a library that has low-level system access.