How to Install the Keyboard Module (Python 3.12.3) on Linux Mint

I remember the first time I tried to capture key presses on my Linux Mint machine python I was building a little productivity tool, and every time I ran:

pip3 install keyboard

I was met with this bewildering message:

× This environment is externally managed
╰─> To install Python packages system-wide, try apt install python3-xyz...
...
hint: See PEP 668 for the detailed specification.

I scratched my head. “What does ‘externally managed’ even mean?” I’ll walk you through exactly how I solved it—step by step—and share the little project I built along the way. By the end, you’ll not only have a working keyboard setup, but also a handful of practice snippets to extend your skills.

What “externally managed” Really Means

When you see:

× This environment is externally managed
╰─> To install Python packages system-wide, try apt install...
hint: See PEP 668 for the detailed specification.

…it simply means your system Python (the one in /usr/bin/python3) is locked down by Linux Mint’s package manager. They don’t want you accidentally breaking core OS tools by mixing pip packages with Debian‑packaged ones.

Key takeaways for me:

• Never run sudo pip3 install keyboard against the system interpreter.
• Always isolate third‑party packages in a virtual environment or use a user‑level installer like pipx.

Two Clean Ways to Install keyboard

A. Virtual Environment

• Install the full Python toolchain (if needed):

sudo apt update
sudo apt install python3-full python3-venv

• Create and activate a new venv:

python3 -m venv ~/projects/keyboard-demo/venv
source ~/projects/keyboard-demo/venv/bin/activate

• Install the package:

pip install --upgrade pip
pip install keyboard

• Run your scripts with the same python inside venv/bin/python.

B. pipx for Quick CLI Scripts

If I just need to run a one‑off script without juggling environments, I use pipx:

• Install pipx:

sudo apt install pipx
pipx ensurepath

• Install keyboard in its own isolated space:

pipx install keyboard

• Run any script like so:

pipx run --spec keyboard python myscript.py

pipx handles the environment for me, so I never touch my system Python.

Building a Simple Key‑Press Project

Once you’ve installed keyboard, let’s build a small demo. I call mine demo_keyboard.py:

# demo_keyboard.py

import keyboard   # ← This line will work once your env is set up!

def on_space_press(event):
    """Print a message whenever the spacebar is pressed."""
    print("You hit SPACE!")

def main():
    # Link the spacebar to our callback
    keyboard.on_press_key("space", on_space_press)
    
    print("Press ESC to exit.")
    # Blocks here until user presses Esc
    keyboard.wait("esc")

if __name__ == "__main__":
    main()

Breakdown:

1. Import: If this errors (ModuleNotFoundError), double‑check that you’re running the correct Python.
2. Callback: on_space_press fires on every spacebar event.
3. Listener: keyboard.on_press_key("space", ...) wires your function up.
4. Exit: keyboard.wait("esc") keeps the script alive until you hit Esc.

Practice Snippets to Level Up

After getting the basics running, I like to experiment. Here are a few of my favorite exercises:

A. Key Logger

keyboard

print("Recording key events. Hit ESC to stop.")
events = keyboard.record(until="esc")
for e in events:
    print(f"{e.name} | {e.event_type} | {e.time:.3f}")

Goal: Capture keystrokes and timestamps for simple analytics or debugging.

Custom Hotkey

keyboard

# Map Ctrl+Shift+S to a custom “save” action
keyboard.add_hotkey("ctrl+shift+s", lambda: print("Save hotkey triggered!"))

print("Waiting for Ctrl+Shift+S... ESC to quit.")
keyboard.wait("esc")

Goal: Bind complex key combinations to any Python function.

Macro Playback

keyboard, time

print("Press ENTER to start recording; ESC to stop.")
keyboard.wait("enter")
macro = keyboard.record(until="esc")

print("Replaying in 3 seconds...")
time.sleep(3)
keyboard.play(macro)

Goal: Record and replay user actions—handy for demos or repetitive tests.

Block a Key

keyboard

# Disable Caps Lock entirely
keyboard.block_key("caps lock")
print("Caps Lock is now blocked. ESC to quit.")
keyboard.wait("esc")

Goal: Suppress keys you never use (good for public kiosks or demo machines).

Final Thoughts

I’ve walked you through why Linux Mint won’t let you pip install into its system Python, two safe installation methods, a simple demo project, and several practice snippets. By isolating your work in virtual environments or through pipx, you keep your OS stable while enjoying powerful libraries like keyboard. Now it’s your turn fork these examples, mash up the snippets, and build the next generation of hotkey‑powered Python tools.