Debugging on a Machine You Can't Install Anything On: PyCharm's SSH Interpreter

The laptop that can't run the code

Here's a familiar situation: your training script needs a CUDA GPU, your ETL job needs network access to an internal database, or your service only behaves correctly inside a production-like container. Your laptop fails on at least one of those counts. The usual workaround — editing locally, copying files over with scp, running in a terminal, reading logs — works, but it throws away the two things an IDE is good at: running and debugging.

PyCharm Professional has a well-established answer: configure the project's Python interpreter to live on a remote host over SSH. You keep editing in the local IDE, but when you press Run or Debug, the code executes on the remote machine with the remote Python, the remote environment variables, and the remote hardware. Breakpoints, variable inspection, and stepping all work as if the process were local.

Note the edition requirement up front: remote interpreters are a Professional-only feature. The free Community edition doesn't include them.

How the pieces fit together

Two configurations do all the work, and confusing them is the source of most frustration:

• The SSH interpreter (Settings > Project > Python Interpreter, then add an interpreter "On SSH") tells PyCharm which Python to run and where. You point it at a host, credentials, and a Python executable on that host — often inside a virtualenv or conda environment.
• The deployment configuration (Tools > Deployment) defines the path mappings between your local project directory and the directory on the remote host where files get synced. PyCharm uploads your sources there before running.

The mental model: your local checkout is the source of truth, PyCharm mirrors it to the remote path, and the remote interpreter executes that mirrored copy. Once that clicks, the failure modes become predictable.

A worked example: debugging a training script on a GPU server

Say you're a data engineer with a CUDA-enabled server at gpu-box.internal and a local project ~/projects/train-model. The setup looks like this:

1. Create the deployment configuration first: Tools > Deployment > Configuration, add an SFTP entry for gpu-box.internal, and on the Mappings tab set the local path ~/projects/train-model to a remote path like /home/you/train-model. Enable automatic upload so saves sync without manual steps.
2. Add the interpreter: Settings > Project > Python Interpreter > Add Interpreter > On SSH. Enter the host and credentials, then point to the remote Python, e.g. /home/you/venv/bin/python. PyCharm will offer to reuse or create the deployment mapping — keep it consistent with step 1.
3. Verify with a canary script before trusting anything:

import socket, sys
print("host:", socket.gethostname())
print("python:", sys.executable)

Run it with the new interpreter. The output should show the remote hostname and the remote Python path — not your laptop's. If it shows your local machine, the run configuration is still bound to a local interpreter.

Now the payoff: open your training script, set a breakpoint on the loss computation, and hit Debug. Execution pauses on the GPU server, and you can inspect tensors on the live CUDA device, step through the data pipeline, and evaluate expressions against the real environment. No log-line archaeology.

Where it goes wrong

Stale code. If automatic upload is off or a file was excluded, you debug an older copy of your code and chase bugs you already fixed. If behavior doesn't match what you're reading in the editor, suspect the sync first: force an upload (Tools > Deployment > Upload) and rerun. A deliberate way to build intuition for this: edit a print statement locally without syncing, rerun, and watch the old output appear.

Wrong path mappings. "File not found" errors and breakpoints that never bind almost always trace back to a mapping that doesn't match where the interpreter actually runs the code. The canary script above doubles as a diagnostic: compare sys.executable and the working directory against your deployment mapping.

Remote edits getting clobbered. If someone (or something) edits files directly on the server, an automatic upload from your local checkout can silently overwrite those changes. Treat the local copy as canonical, or download remote changes before uploading.

The trade-off you should know about

This model keeps the source of truth on your laptop and syncs files to the target. For modest projects on decent links, that sync is invisible. For large codebases, big generated artifacts, or a slow VPN, upload lag becomes a real tax on every run — and everything still depends on your laptop being awake and connected.

JetBrains' newer remote development offering takes the opposite approach: the IDE backend and the code both live on the remote machine, and your laptop runs a thin client. That removes the sync problem but changes your setup, licensing, and version requirements. The details have shifted across releases, so check the current PyCharm documentation before committing a team to either model. The same caveat applies to exact menu paths above — they've moved between versions; the concepts (interpreter over SSH, deployment mappings) have been stable for years.

Worth knowing: Docker, Docker Compose, and WSL interpreters in PyCharm follow the same conceptual model — a non-local Python plus a mapping between your sources and where they execute. Everything in this post transfers.

Try it this afternoon

Pick one script that currently only runs after a manual copy-to-server dance. Set up the deployment mapping, add the SSH interpreter, run the hostname canary, then set one breakpoint and debug it. That fifteen-minute exercise tells you whether the workflow fits your project size and network — and once the mapping is right, every future debugging session on that remote resource stops being a terminal-and-logs exercise.