Connecting to a Python development environment in a remote Docker container from VSCode

 Posted on January 3, 2026  |    • Other languages: ja

Motivation

Until now, I’ve been launching JupyterLab containers on a remote workstation equipped with a GPU, connecting via browser from my local MacBook Air to develop Python code. For example, see this article. Recently, since I’ve been using VSCode frequently, I tried connecting to the same Python development environment on the GPU-equipped remote workstation from VSCode.

Information Sources

I usually build things by referencing online information, but this time I built it while asking Claude. That said, I did consult the PyTorch page to verify compatibility between the CUDA version and the torch installation.

I started with a prompt like this:

I want to build a Python environment using uv within a Docker container on an Ubuntu server with a GPU (NVIDIA driver version: 580.95.05). Please provide a Dockerfile to create the Docker container, using PyTorch as the framework.

I use uv as a Python package manager.

Setup

Server-side

Dockerfile

I created the following Dockerfile based on Claude’s response.

# NVIDIA CUDAベースイメージを使用
FROM nvidia/cuda:12.4.0-runtime-ubuntu22.04

# 環境変数の設定
ENV DEBIAN_FRONTEND=noninteractive \
    PYTHONUNBUFFERED=1 \
    HOME=/root

# 作業ディレクトリの設定
WORKDIR /workspace

# 必要なパッケージのインストール
RUN apt-get update && apt-get install -y \
    curl \
    git \
    build-essential \
    ca-certificates \
    wget \
    && rm -rf /var/lib/apt/lists/*

# uvのインストール
RUN curl -LsSf https://astral.sh/uv/install.sh | sh

# Pythonのインストール（フルパス指定で確実に）
RUN /root/.local/bin/uv python install 3.11

# 仮想環境の作成
RUN /root/.local/bin/uv venv /opt/venv --python 3.11

# PATHを一度にまとめて設定（これが重要）
ENV PATH="/opt/venv/bin:/root/.local/bin:/usr/local/nvidia/bin:/usr/local/cuda/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" \
    VIRTUAL_ENV="/opt/venv"

# インストール確認
RUN uv --version && python --version

# PyTorchとその依存関係をインストール
RUN uv pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124

# よく使うライブラリもインストール
RUN uv pip install \
    numpy \
    pandas \
    matplotlib \
    jupyter \
    ipython \
    tqdm \
    scikit-learn \
    scipy \
    seaborn \
    plotly

# Jupyter Notebookのポートを公開
EXPOSE 8888

# .bashrcに仮想環境のアクティベートを追加
RUN echo 'source /opt/venv/bin/activate' >> /root/.bashrc

CMD ["/bin/bash"]

Build the Container

Run the following in the directory containing the Dockerfile to create a Docker container.

sudo docker build -t pytorch-uv ./

Start the Container

Use the following command to start the built container. This is set up as a shell process. Please modify NB_DIR according to your specific environment.

export NB_DIR=/mnt/nfs2
export CUDA_VISIBLE_DEVICES=0
sudo docker run --gpus all -it --rm  -v ${NB_DIR}:/workspace -p 8888:8888 pytorch-uv:latest

Client Side

Prerequisites for client-side work: VS Code is already installed, and an SSH connection to the server is established.

Install VS Code Extensions

Install the following extensions in VS Code:

  • Remote-SSH
  • Docker
  • Dev Containers

Configuring the SSH Connection

Launch VS Code and configure the SSH connection (in ~/.ssh/config) using the following steps:

  1. Open the Command Palette (Cmd+Shift+p)
  2. Select Remote-SSH: Connect to Host…
  3. Choose Configure SSH Hosts… to edit ~/.ssh/config
Host host-name
    HostName IP-address
    User user-name
    IdentityFile ~/.ssh/id_rsa
    Port 22
    ForwardAgent yes

Please adjust the host-name, IP-address, and user-name sections according to your own environment.

Connecting to the Host

Connect to the host in VS Code using the following steps:

  1. In the Command Palette, select Remote-SSH: Connect to Host…
  2. Select the host-name configured above
  3. When prompted for a password during the SSH connection attempt, enter the password
  4. A new VS Code window will open

Connecting to a Container

  1. In the Command Palette, select Dev Containers: Attach Running Container…
  2. Select the desired running container
  3. A new VS Code window opens, connecting you inside the container

Checking/Changing Python Version

If the Python built in your Dockerfile isn’t being used (this is where I got stuck), follow these steps to use the container’s Python:

  1. Click the Python version indicator in the bottom-right corner of VS Code
  2. Select /opt/venv/bin/python

Summary

I set up a Python development environment with Claude as my assistant. Instead of searching online, whenever an error occurred, I simply described the situation accurately to Claude, and it provided solutions, making the setup relatively straightforward.

Next, I’ll use this development environment to run the PINN project I was working on around this time last year.

VSCode  python  docker