Sam Austinon November 7, 202618 min read

How to Run Research Code from a Paper's GitHub Repo (and Fix the Dependency Errors)

How to Run Research Code from a Paper's GitHub Repo (and Fix the Dependency Errors)
Contents

Figure 1: How to Run Research Code — you find a paper with great results and a GitHub link. You clone the repo, run pip install, and the terminal fills with red. Three hours later, you've installed four versions of PyTorch and your GPU still says "no kernel image is available."

You find a paper with great results and a GitHub link. You clone the repo, run pip install -r requirements.txt, and the terminal fills with red. Three hours later, you've installed four versions of PyTorch and your GPU still says "no kernel image is available." Sound familiar? Research code usually runs fine on exactly one machine: the author's, in the month they submitted.

I cannot claim I have run your specific repo, and I have not executed the commands below in this conversation, so test them in a scratch environment first. IMO, getting old research code to run is a method, not luck. Most people fight errors one at a time instead of recreating the environment the authors actually used. Let us fix that.

Why Research Code Breaks

Research repos are not products. Authors write them to produce paper results, often under deadline pressure. Then the ecosystem moves on:

  • Libraries change APIs. Functions get renamed, removed, or reinterpreted.
  • Pins vanish. Many repos list torch with no version, so you get today's release.
  • Hardware moves. New GPUs need newer CUDA builds that old PyTorch versions do not include.
  • Links die. Datasets and checkpoints disappear from personal servers.
  • Nobody maintains it. Many repos have a "last commit" older than your coffee machine.

Ever wondered why a repo with a clean README still explodes on install? The README describes the author's world, not yours.

Step 1: Read Before You Run

Spend ten minutes on reconnaissance. It saves hours.

Check the Repo's Age and Health

git log -1 --format=%cd      # date of last commit
git log --reverse --format=%cd | head -1   # first commit date

Those dates tell you which library versions the authors probably used. A repo last touched in 2021 expects 2021's Python, PyTorch, and CUDA.

Read the Issues First

Open the Issues tab and search for "install," "error," "version," and "reproduce." Someone has almost certainly hit your error already. A closed issue with a working fix beats an hour of guessing. Pay attention to comments from the authors, because they often reveal the real versions.

Collect the Environment Clues

Look for these files:

  • requirements.txt, environment.yml, pyproject.toml, setup.py
  • Dockerfile or docker-compose.yml
  • README notes like "tested with Python 3.8 and PyTorch 1.10"
  • CI configs under .github/workflows, which sometimes reveal the tested versions

Write down every version you find. You will use them in Step 3.

Scan for Risks

Read install scripts, Makefile targets, and any curl | bash lines before you run them. Research repos sometimes download datasets or binaries from personal servers. Never run unknown shell scripts outside a sandbox.

Step 2: Isolate the Environment

Never install a research repo into your main Python environment. Pick one isolation tool:

  • Conda or mamba: handles Python versions and some system libraries
  • venv or uv: lightweight, and uv creates environments quickly
  • Docker: best for reproducibility and for keeping repo code away from your host
# Conda example (pick the Python version from your clues)
conda create -n paper-repo python=3.9 -y
conda activate paper-repo

# uv example
uv venv --python 3.9
source .venv/bin/activate

I have not run these here, so check your tool's current syntax. Match the Python version to the repo's era first. A 2020 repo rarely likes Python 3.12, and the failure often looks like a mysterious build error.

Step 3: Recreate the Authors' Era

This step solves most dependency problems. Instead of installing "latest of everything," install what existed when the authors wrote the code.

Pin Python, Torch, and CUDA First

Install the deep learning framework before the rest of the requirements, using the selector on the official PyTorch site for your CUDA setup. Then check what you got:

import torch
print(torch.__version__, torch.version.cuda, torch.cuda.is_available())

Run nvidia-smi too. It shows your driver's maximum supported CUDA version. PyTorch wheels bundle their own CUDA runtime, so you usually do not need to install a matching CUDA toolkit. You only need nvcc when the repo compiles custom CUDA extensions.

Install Packages as of a Date

If the requirements file does not pin versions, try installing with a date cutoff. The uv tool offers an option for this:

uv pip install --exclude-newer 2021-06-01 -r requirements.txt

That asks the resolver to ignore releases published after the date you choose. I have not run this here, so confirm the option in uv's current docs. Without uv, you can pin old versions manually by reading release dates on each package's PyPI page.

Install Torch Separately, Then the Rest

pip install torch==<version> --index-url https://download.pytorch.org/whl/<cuda-tag>
pip install -r requirements.txt --no-deps   # only if you know what you're doing
pip check                                   # lists broken dependency pairs

--no-deps skips dependency resolution, so use it carefully and follow it with pip check. If pip check reports conflicts, fix those pairs deliberately.

A Warning About New GPUs

If you own a recent GPU, an old PyTorch build may not include kernels for it. The symptom is an error like "no kernel image is available for execution on the device." The fix is not a different CUDA toolkit. You need a newer PyTorch build that supports your GPU, which means updating the repo's code for newer APIs. Plan for that.

Step 4: Fix the Errors You Will Actually Meet

Read each traceback from the bottom up. The last lines name the real problem. Here are the errors I would expect most often, with fixes.

ModuleNotFoundError or ImportError

The package is missing, renamed, or a different version moved the function.

  • Missing package: install it, and add it to your notes
  • cannot import name 'X' from 'Y': the library changed its API, so find the version that still has X, or update the import
  • Import works only from the repo root: run commands from the repo directory, or install the repo with pip install -e .

NumPy Problems

Two classic ones:

  • AttributeError: module 'numpy' has no attribute 'float' (or int, bool): NumPy removed those aliases in version 1.24. Replace them with float, int, bool, or np.float64, or install an older NumPy.
  • "A module that was compiled using NumPy 1.x cannot be run in NumPy 2.x": NumPy 2.0 broke binary compatibility with extensions built against 1.x. Install numpy<2 and reinstall the affected packages.
pip install "numpy<2"

Pandas and Scikit-Learn Deprecations

DataFrame.append disappeared in pandas 2.0, so replace it with pd.concat. Scikit-learn removes deprecated arguments over time, so check the error message for the replacement name.

distutils and setuptools Failures

Newer Python versions dropped distutils, and old setup.py files sometimes break. Either use an older Python, install a compatible setuptools, or update the build file. If a package fails to build from source, look for a prebuilt wheel for your Python version first.

Gym vs. Gymnasium

RL repos hit this constantly. Newer environment APIs changed what reset() and step() return:

# Old style
obs = env.reset()
obs, reward, done, info = env.step(action)

# Newer style
obs, info = env.reset()
obs, reward, terminated, truncated, info = env.step(action)
done = terminated or truncated

Either pin the old gym version the repo expects, or update the code to the new Gymnasium API and handle terminated and truncated separately. If a repo uses mujoco-py, expect pain: it needs specific MuJoCo binaries and compilers. The maintained mujoco Python bindings usually work better, but you must adapt the environment code.

torch.load and Checkpoint Errors

Recent PyTorch versions changed torch.load defaults to be safer, so old checkpoints that pickle arbitrary objects may fail to load. Pickle files can execute code when loaded, so do not just flip the safety flag to make the error go away:

# Only for files you trust completely:
state = torch.load(path, map_location="cpu", weights_only=False)

If the checkpoint came from an unknown source, do not load it. Prefer safetensors files, or ask whether the authors provide weights in a safer format. When in doubt, load it inside a throwaway container.

CUDA Extension Build Failures

Errors mentioning nvcc, gcc, or cuda_runtime.h mean the repo compiles custom CUDA code. Check:

  • Compiler compatibility: old CUDA toolkits reject new gcc versions
  • CUDA toolkit version vs. PyTorch's CUDA version: a mismatch breaks the build
  • Prebuilt wheels: a published wheel for your exact torch and CUDA combination beats compiling
  • Environment variables: variables like CUDA_HOME often need setting

If the build keeps failing, look for a pure-PyTorch alternative or a newer fork.

Missing System Libraries

Errors like libGL.so.1: cannot open shared object file or missing ffmpeg mean you need operating system packages, not Python packages. Install them through your system package manager, or use a Docker base image that includes them.

Protobuf and TensorFlow Conflicts

TensorFlow 1.x repos want ancient Python versions and specific protobuf releases. Treat those as archaeology projects: use a container, pin everything, and do not mix them with modern libraries. If you only need the idea, consider a modern reimplementation.

Step 5: Fix Things Methodically

Random pip installs create a mess. Use this loop instead:

  1. Reproduce the error with the shortest command that triggers it
  2. Read the last lines of the traceback and note the library and version
  3. Search the repo's issues and the library's changelog for that message
  4. Change one thing, then rerun
  5. Log the change in a notes file
  6. Repeat until the smoke test passes

Keep a Setup Log

pip freeze > requirements.lock     # snapshot a working environment

Also write a SETUP_NOTES.md listing Python version, PyTorch and CUDA versions, every code edit, and the exact commands that worked. Future you will thank present you. :)

Use Dependency Tools

pip check              # find broken dependency pairs
pipdeptree             # show which package requires which (install it first)

When two packages demand incompatible versions of a third, pipdeptree shows you who asked for what.

Step 6: Handle Dead Data and Missing Checkpoints

Even a working environment can fail on downloads.

  • Dead dataset links: check the issues, the paper's appendix, and mirrors on Hugging Face or other hosts
  • Missing checkpoints: search the issues, and look for forks that re-hosted weights
  • Gated or licensed data: some datasets require applications or agreements, so read the terms
  • Wrong preprocessing: if the repo expects preprocessed data, find the script that creates it before you fake the format
  • Authors: a polite, specific email sometimes gets files back. Include the paper title, what you tried, and the exact error.

Verify downloaded files against any checksums the repo publishes, and avoid executing code that arrives with data.

Step 7: Run the Smallest Thing First

Before you launch anything big, prove the pipeline works:

  • Smoke test: one batch, one step, tiny model
  • Toy subset: a few hundred examples
  • Fixed seed: so you can compare reruns
  • CPU mode: errors surface faster when you remove GPU variables

If a one-batch run fails, a 48-hour run will fail later and more expensively.

Step 8: Reproduce One Number

A working run is not a reproduction. Choose one result from the paper or README and try to match it. Expect some variance:

  • Seeds: run several, and compare the spread to the reported number
  • GPU nondeterminism: some operations do not produce identical results across runs or hardware
  • Library versions: different versions can shift results slightly
  • Hidden details: the paper may omit preprocessing or evaluation choices that the code includes

If you land within a reasonable range, you have reproduced it. If you miss by a lot, compare your config against the paper line by line, check issues for known gaps, and consider that the published number may not reproduce. That happens, and it is useful to know. For a broader method on reading repos and judging them before adoption, see the earlier articles in this series.

When to Stop Fighting

Sometimes the right move is to quit the old stack. Consider alternatives when:

  • The repo needs unsupported hardware or abandoned libraries
  • You have spent a day with no smoke test passing
  • The core algorithm is small, and rewriting it cleanly takes less time than repairing the environment
  • A maintained reimplementation exists in a library you already trust

Rewriting the core idea in a modern framework also forces you to understand it. That is a real benefit, not a defeat.

A Short Checklist

Copy this into your notes:

  1. Check the commit dates, issues, and environment clues
  2. Read install scripts before running them
  3. Create an isolated environment with an era-appropriate Python
  4. Install PyTorch (or TensorFlow) first, then everything else
  5. Try date-pinned installs for unpinned requirements
  6. Run pip check and fix conflicts deliberately
  7. Fix errors one at a time, and log each change
  8. Find replacements for dead data and checkpoints
  9. Run a smoke test, then a small run
  10. Reproduce one published number across several seeds
  11. Freeze the working environment and write setup notes

Common Mistakes to Avoid

  • Installing into your main environment. One bad repo can poison everything.
  • Using the latest of everything. The authors did not.
  • Fixing five errors at once. You will not know which change worked.
  • Disabling safety checks without thinking. Loading untrusted pickles can run code.
  • Skipping the issues tab. Someone already hit your error.
  • Launching the full run first. Smoke tests catch most failures cheaply.
  • Not recording what worked. You will repeat the same debugging next month.
  • Assuming a result must reproduce. Sometimes it does not, and the paper is the problem.

Did you notice that most mistakes involve skipping reconnaissance?

Final Thoughts

Running research code is archaeology with a terminal. Find out when the code was written, rebuild that world in an isolated environment, fix errors one at a time, and prove it works with a smoke test and one reproduced number. Keep notes, and know when a rewrite beats a repair.

So pick one repo you have been avoiding this week and spend an hour on Steps 1 through 3. Write down the Python, PyTorch, and CUDA versions you settle on. If the smoke test passes, you have done the hard part. If it does not, congratulations: you now have a precise error message to search, and that beats a vague sense of dread.

Frequently Asked Questions

Why does research code often fail to run on my machine?

Research repos are built for the author's specific environment (Python, PyTorch, CUDA versions from the time of writing). Library APIs change, CUDA versions shift, and dependencies drift. You need to recreate the author's environment, not use the latest of everything.

How do I know which Python and PyTorch versions to use?

Check the repo's last commit date, README, issues, and CI configs. The last commit date tells you the era — a 2021 repo expects 2021's Python, PyTorch, and CUDA versions.

What should I do when pip install -r requirements.txt fails?

Do not install everything at once. Install PyTorch first with the correct CUDA tag, then install other packages. Use uv pip install --exclude-newer <date> to install packages as of a specific date. Use pip check to find conflicts.

What should I do when a checkpoint fails to load with torch.load?

If you trust the source completely, use torch.load(path, map_location='cpu', weights_only=False). Otherwise, prefer safetensors files. Never disable safety checks for untrusted checkpoints — pickle files can execute code.

How do I handle a repo that uses the old gym API instead of gymnasium?

Either pin the old gym version the repo expects, or update the code to the new Gymnasium API (new reset() and step() signatures). Update the environment code accordingly.

Sources

What are You Looking For?

esc