PyCharm Debugger (pydevd-pycharm)

Warnings

• gotcha Most users do not need to install `pydevd-pycharm` manually via pip. PyCharm bundles and manages its own version internally. Manual installation is primarily for remote debugging scenarios where the target environment (e.g., a server, Docker container) does not have PyCharm installed.
  Fix: Only install this package directly if you are setting up remote debugging and need to inject the debugger client into an environment. Otherwise, rely on your PyCharm installation.
• breaking The internal communication protocol and API parameters for `settrace` can change between major PyCharm/IDEA releases. An older `pydevd-pycharm` client might not be fully compatible with a newer PyCharm IDE, and vice-versa, leading to debugging issues or failures to connect.
  Fix: Ensure the `pydevd-pycharm` version installed in your remote environment is compatible with your PyCharm IDE version. Typically, upgrading `pydevd-pycharm` in your remote environment to match your IDE's recent version is the solution.
• gotcha Remote debugging requires careful network configuration. Firewall rules, network access control lists (ACLs), or incorrect IP addresses/ports can prevent the debugger client from connecting to the PyCharm IDE. Common issues include 'Connection refused' or 'Timeout' errors.
  Fix: Verify that your PyCharm IDE is listening on the correct host/port. Ensure there are no firewalls blocking traffic between the debugged application and the IDE. Use the actual IP address of the PyCharm machine, not 'localhost', if they are on different machines or within Docker networks.
• gotcha Running code under a debugger, especially with `stdoutToServer=True` or `stderrToServer=True`, can introduce noticeable performance overhead. This is generally expected for debugging tools but can be significant in performance-critical applications.
  Fix: Disable debugger features that are not strictly needed (e.g., `stdoutToServer`, `stderrToServer` if console output isn't critical to debug) or remove `settrace` calls entirely for production environments. Only debug when necessary.

Install

• pip install pydevd-pycharm Install via pip

Imports

• settrace

  from pydevd_pycharm.pydevd import settrace

  While PyCharm often simplifies to 'import pydevd', the explicit path 'from pydevd_pycharm.pydevd import settrace' is more reliable for direct pip installations as 'pydevd' might not be a top-level module.

Quickstart

This example demonstrates how to set up remote debugging with `pydevd-pycharm`. It instructs the Python process to connect to a PyCharm debugger server running on a specified host and port. This is typically used when debugging code running in a separate environment (e.g., a Docker container, remote server) from your PyCharm IDE. Ensure your PyCharm IDE is configured to listen for remote debug connections on the specified host and port.

import os
from pydevd_pycharm.pydevd import settrace

# Configure PyCharm for remote debugging first (Run -> Edit Configurations -> Python Remote Debug).
# Get the host and port from your PyCharm setup.
# The host should be the IP address of the machine running PyCharm (e.g., your local machine's IP).
# The port is what PyCharm is listening on (e.g., 51235).

PYCHARM_DEBUG_HOST = os.environ.get('PYCHARM_DEBUG_HOST', 'localhost')
PYCHARM_DEBUG_PORT = int(os.environ.get('PYCHARM_DEBUG_PORT', '51235')) # Check PyCharm config for actual port

print(f"Attempting to connect to PyCharm debugger at {PYCHARM_DEBUG_HOST}:{PYCHARM_DEBUG_PORT}...")

try:
    # suspend=False means the program will not wait for the debugger connection at this point.
    # settrace() will attempt to connect and continue execution if it fails.
    settrace(
        host=PYCHARM_DEBUG_HOST,
        port=PYCHARM_DEBUG_PORT,
        suspend=False, # Set to True if you want execution to pause until debugger connects
        stdoutToServer=True,
        stderrToServer=True
    )
    print("Debugger connection established (or attempted).")
except Exception as e:
    print(f"Failed to connect to debugger: {e}")

# Your application logic continues here
def my_function():
    message = "This line can be a breakpoint in PyCharm."
    print(message)
    return message

if __name__ == '__main__':
    my_function()