Getting a Research Paper's Code Actually Running

We write about papers most weeks, and a fair number come with code. The gap between “the code is public” and “the code runs on your machine” is where most people give up — usually after an hour of dependency errors that look like a problem with their computer rather than a problem with the repository.

It is almost always the repository. Research code is written to produce results for a deadline, by someone who will never install it again.

The Code City on the general mechanics of running a downloaded Python project.

Step 0: decide whether to bother, in five minutes

Before installing anything, read the repo for these signals:

Good signs:

Last commit within a year
Open issues with replies from the authors
A requirements.txt or environment.yml with pinned versions
A stated CUDA/PyTorch version
A Colab notebook or a Hugging Face Space
Checkpoints on Hugging Face rather than a Google Drive link

Bad signs:

“Code coming soon” (it usually isn’t)
No dependency file at all
requirements.txt with no version numbers
Checkpoint links to a university FTP server
Issues titled “does not work” with no response
The paper is from a large lab and the repo has no license

If there’s a Hugging Face Space, start there. Five minutes in someone else’s working environment tells you whether the technique does what you want, which is the question you actually have. Do the local install afterwards, if the answer is yes.

Step 1: isolate, always

Never install research code into your system Python. These repos pin ancient versions and fight each other.

The fast modern option is uv:

curl -LsSf https://astral.sh/uv/install.sh | sh

git clone https://github.com/someone/somepaper
cd somepaper
uv venv --python 3.10
source .venv/bin/activate
uv pip install -r requirements.txt

uv resolves in seconds where pip takes minutes, and it fails fast and legibly on conflicts.

If the repo ships an environment.yml, use conda/mamba instead — the file exists because they needed non-Python binaries:

conda env create -f environment.yml
conda activate whatever-they-called-it

Which Python version? If unstated, look at the repo’s date and pick what was current then. A 2023 paper wants 3.10, not 3.13. This one line resolves a surprising share of install failures.

Step 2: the CUDA and PyTorch negotiation

This is where most attempts die, and the mental model that fixes it is short:

Your driver supports CUDA up to some version — check with nvidia-smi (top right)
PyTorch wheels ship their own CUDA runtime. You do not need a matching system CUDA toolkit for ordinary PyTorch use
So the thing to match is PyTorch’s CUDA build against your driver, not against a system install

nvidia-smi                      # driver + max supported CUDA
python -c "import torch; print(torch.__version__, torch.version.cuda, torch.cuda.is_available())"

If torch.cuda.is_available() is False, you almost certainly have a CPU-only wheel. Reinstall explicitly:

uv pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121

Install torch first, alone, and verify it, before anything else. Then install the rest. Letting requirements.txt pull torch as a transitive dependency is how you get a CPU build silently.

The exception — when you do need a real CUDA toolkit: any package that compiles CUDA kernels at install time. Custom ops, flash-attn, many Gaussian-splatting and NeRF repos, anything with a setup.py invoking nvcc. Those need a system toolkit whose version matches your PyTorch’s CUDA version, and nvcc --version must agree. This is the single most painful category; if a compile fails, check that pairing first.

On Apple Silicon: there is no CUDA. Some code runs on mps, much doesn’t, and a fair amount assumes CUDA unconditionally. Look for a --device flag; expect to patch .cuda() calls to .to(device). Budget real time or use a rented GPU.

Step 3: find the weights

Papers separate code from checkpoints, and the README often mentions weights once, in passing.

Look in: the README (search “checkpoint”, “weights”, “pretrained”, “ckpt”), the releases tab, the repo’s Hugging Face org, scripts/download_*.sh, and the issues (someone has asked).

Then check where the code expects them. Usually a hardcoded relative path in a config or demo.py:

grep -rn "\.pth\|\.ckpt\|\.safetensors\|checkpoint" --include="*.py" --include="*.yaml" . | head -30

Put the file exactly where that path says. A large fraction of “it doesn’t work” is a checkpoint in the wrong folder.

Step 4: run the smallest thing

Do not start with the full training script or the paper’s headline result. Find, in order of preference: demo.py, inference.py, app.py, a notebook in notebooks/, or the example in the README.

Run it on the sample input they provide, unmodified, before your own data. If their example fails, the problem is the install. If their example works and yours fails, the problem is your input format — a completely different investigation, and you want to know which one you’re in.

The five errors you will actually hit

ModuleNotFoundError for something obvious — the requirements file is incomplete. Just uv pip install it. This is normal, not a bad sign.

ImportError: cannot import name X from Y — a version mismatch in a transitive dependency. Most often numpy 2.x against code written for 1.x, or huggingface_hub having moved a symbol. Pin it down:

uv pip install "numpy<2"

CUDA out of memory — look for --batch_size, resolution, or --half/--fp16 flags. Failing that, reduce whatever number is largest in the config.

nvcc fatal / compile failure — the toolkit/PyTorch CUDA mismatch from Step 2. Check for a prebuilt wheel before fighting it; flash-attn and similar often have one for your exact torch+CUDA+Python combination.

Silent wrong output — the worst case, and usually a checkpoint that loaded partially. Look for a strict=False in a load_state_dict call, and for warnings about missing or unexpected keys that the script prints and ignores.

When to stop

Set a budget — two hours is reasonable — and if the install is still failing, consider:

A Docker image, if they ship one. docker run past every environment problem at once. This is the correct answer far more often than people reach for it.

Rented GPU time. Colab, or a cloud instance with a clean CUDA image. An hour of GPU rental is cheaper than an evening.

An open issue. Authors often respond, and if they don’t, your issue helps the next person.

Someone’s reimplementation. Search the paper title on GitHub. Third-party reimplementations are frequently better packaged than the original, precisely because they were written by someone who had to install it.

Or nothing. A repo that nobody but the authors has run is a real category. Knowing when to walk away is part of the skill.

The habit worth building

Write down what worked. A three-line note in the repo folder — Python version, torch version, CUDA version, the command that ran — will save you an hour when you come back in four months. Nobody does this and everybody wishes they had.