Configure PyCharm Professional Remote Development Over SSH

Problem and Takeaway

You want to edit code locally in PyCharm while executing, debugging, and interacting with a terminal on a remote Linux server. PyCharm Professional's Remote Development feature makes this possible by mapping a local project to a remote Python interpreter over SSH. The key takeaway: set up an SFTP deployment configuration first, then attach a remote interpreter, and finally verify that run/debug sessions actually execute on the remote host.

Prerequisites

• PyCharm Professional 2023.1 or later – Community Edition does not support remote interpreters.
• Remote Linux/macOS host with Python 3.8+ installed and reachable via SSH.
• SSH key-based authentication configured (password auth works but keys are more reliable for automation).
• Project source accessible on the remote host – either already present or synced via PyCharm's deployment.
• TCP forwarding enabled on the SSH server (AllowTcpForwarding yes in /etc/ssh/sshd_config) for debugger port forwarding.

Procedure

1. Create an SFTP Deployment Configuration

1. Open Settings → Build, Execution, Deployment → Deployment.
2. Click + → SFTP. Name it (e.g., remote-dev).
3. Fill in:
   Host: remote server IP or hostname
   Port: 22 (or custom)
   User name: your remote user
   Authentication: Key pair – select your private key (e.g., ~/.ssh/id_ed25519) and enter passphrase if set.
4. Click Test Connection. Success shows a green banner.
5. Switch to the Mappings tab. Map your local project root (e.g., /home/you/projects/myapp) to the remote path (e.g., /home/remoteuser/myapp). Set Deployment path to / for the remote root.
6. Optional: enable Automatic upload (Settings → Deployment → Options) for seamless sync, but see cautions below.

2. Add the Remote Python Interpreter

1. Go to Settings → Project → Python Interpreter → Add Interpreter → On SSH.
2. Select the deployment configuration created above (remote-dev).
3. PyCharm will connect, detect Python versions, and let you choose the interpreter (e.g., /usr/bin/python3.11).
4. Wait for indexing – the remote site-packages will appear in the interpreter paths list.

3. Verify Path Mappings and Exclusions

In Deployment → Mappings, ensure the local-to-remote mapping is correct. Add Excluded Paths for directories that should not sync (e.g., .git, __pycache__, venv, build, dist). This reduces indexing latency and avoids uploading artifacts.

4. Create Run/Debug Configurations Targeting the Remote Interpreter

1. Open Run → Edit Configurations → + → Python.
2. Name it (e.g., Remote Run).
3. Script path: enter the remote path (e.g., /home/remoteuser/myapp/main.py) or use the local path with mapping enabled.
4. Python interpreter: select the remote interpreter you added.
5. Working directory: set to the remote project root.
6. Apply and run/debug.

Expected Checks

• Interpreter validation: In Settings → Python Interpreter, click Show paths for selected interpreter. Confirm remote site-packages are listed.
• Sync test: Modify a local file, then use Tools → Deployment → Sync with Deployed to remote-dev. No errors should appear.
• Remote execution proof: Run a script containing:

  import socket\nprint(socket.gethostname())

  Output must match the remote hostname.
• Debug session: Set a breakpoint, start Debug. The Debug tool window should show remote stack frames and variables.
• Remote terminal: Tools → Start SSH Session → remote-dev opens a shell prompt in PyCharm's terminal tool window.

Common Troubleshooting and Recovery

Limitations and Practical Advice

• Automatic upload can overwrite remote changes made outside PyCharm. In team environments, prefer manual sync (Tools → Deployment → Upload to remote-dev) or rely on version control.
• Initial indexing of large projects (especially with many dependencies) may take minutes. Exclude non-source directories aggressively.
• Windows OpenSSH server works but has limited PTY support; Linux/macOS remote hosts are recommended for full terminal and debugger functionality.
• Fallback: If SSH environment is unstable, consider a Docker-based remote interpreter (Settings → Python Interpreter → Add Interpreter → On Docker) which isolates the runtime.

Verification Checklist

1. Run print(socket.gethostname()) script – output matches remote host.
2. Start debug session with breakpoint – confirm remote frames in Debug tool window.
3. Open SSH session via Tools → Start SSH Session – shell prompt appears.
4. Check interpreter paths – remote site-packages listed.

Once these checks pass, you have a working remote development loop: edit locally, run/debug remotely, with full access to the remote environment's libraries and resources.