From 0941eb7c1102e598eb1feca77cf0d98f9ad5affa Mon Sep 17 00:00:00 2001 From: minsu Date: Wed, 3 Sep 2025 13:38:36 +0900 Subject: [PATCH 1/5] docs: add Google Colab setup and troubleshooting section Add a Colab-specific setup (PyTorch 2.6.0 + CUDA 12.4, MONAI 1.5) and troubleshooting notes (torchaudio mismatch, filelock conflict, num_workers guidance). Include a quick smoke test to verify the environment. Signed-off-by: minsu --- README.md | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/README.md b/README.md index 8aabbe5cf..c6ed84e0f 100644 --- a/README.md +++ b/README.md @@ -41,6 +41,47 @@ Running: in a cell will verify this has worked and show you what kind of hardware you have access to. +#### Google Colab Setup (CUDA 12.x, PyTorch 2.6, MONAI 1.5) + +In Google Colab, the default environment may cause version conflicts with MONAI. +To ensure compatibility, install PyTorch and MONAI explicitly as follows: + +# Install PyTorch 2.6.0 with CUDA 12.4 +pip install --index-url https://download.pytorch.org/whl/cu124 \ + torch==2.6.0 torchvision==0.21.0 torchaudio==2.6.0 + +# Install MONAI and common dependencies +pip install "monai[all]" nibabel pydicom ipywidgets==8.1.2 + + +### Known issues and fixes + +- Torchaudio mismatch + Colab may come with torchaudio 2.8.0, which is incompatible with torch 2.6.0. + Installing the versions above resolves this issue. + +- filelock conflicts with nni + Some preinstalled packages (such as pytensor with newer filelock) may conflict. + Use the following commands to fix: + + pip uninstall -y pytensor + pip install -U filelock + +- Too many workers warning + Colab has limited CPU resources, and high num_workers settings may freeze execution. + It is recommended to use --num_workers=2 when running tutorials. + + +### Quick smoke test + +After installation, verify the environment by running: + +git clone https://github.com/Project-MONAI/tutorials.git +cd tutorials/3d_segmentation/torch +python -u unet_training_array.py --max_epochs 2 --batch_size 1 --num_workers 2 + +If the logs show decreasing training loss and a Dice score, the setup is correct. + #### Data Some notebooks will require additional data. From 2b2bc660ddb7a2d9df1cf1b5e59a2103b3c643b4 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Wed, 3 Sep 2025 05:06:39 +0000 Subject: [PATCH 2/5] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- README.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index c6ed84e0f..e0c0ca0c2 100644 --- a/README.md +++ b/README.md @@ -43,7 +43,7 @@ in a cell will verify this has worked and show you what kind of hardware you hav #### Google Colab Setup (CUDA 12.x, PyTorch 2.6, MONAI 1.5) -In Google Colab, the default environment may cause version conflicts with MONAI. +In Google Colab, the default environment may cause version conflicts with MONAI. To ensure compatibility, install PyTorch and MONAI explicitly as follows: # Install PyTorch 2.6.0 with CUDA 12.4 @@ -56,19 +56,19 @@ pip install "monai[all]" nibabel pydicom ipywidgets==8.1.2 ### Known issues and fixes -- Torchaudio mismatch - Colab may come with torchaudio 2.8.0, which is incompatible with torch 2.6.0. +- Torchaudio mismatch + Colab may come with torchaudio 2.8.0, which is incompatible with torch 2.6.0. Installing the versions above resolves this issue. -- filelock conflicts with nni - Some preinstalled packages (such as pytensor with newer filelock) may conflict. +- filelock conflicts with nni + Some preinstalled packages (such as pytensor with newer filelock) may conflict. Use the following commands to fix: pip uninstall -y pytensor pip install -U filelock -- Too many workers warning - Colab has limited CPU resources, and high num_workers settings may freeze execution. +- Too many workers warning + Colab has limited CPU resources, and high num_workers settings may freeze execution. It is recommended to use --num_workers=2 when running tutorials. From 007f919da81cee8635706bbd256e1cb1d39a14c3 Mon Sep 17 00:00:00 2001 From: Minsu Kim <60283244+minsuking@users.noreply.github.com> Date: Fri, 5 Sep 2025 23:46:45 +0900 Subject: [PATCH 3/5] docs: clarify num_workers guidance in Colab section Co-authored-by: Eric Kerfoot <17726042+ericspod@users.noreply.github.com> Signed-off-by: Minsu Kim <60283244+minsuking@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index e0c0ca0c2..9e3f8d0ac 100644 --- a/README.md +++ b/README.md @@ -69,7 +69,7 @@ pip install "monai[all]" nibabel pydicom ipywidgets==8.1.2 - Too many workers warning Colab has limited CPU resources, and high num_workers settings may freeze execution. - It is recommended to use --num_workers=2 when running tutorials. + It is recommended to use --num_workers=2 when running tutorials and adjust the `num_workers` parameters where it is used in notebooks (eg. for data loaders). ### Quick smoke test From c10ae3543420d48c7b16c1b390102f88b8091116 Mon Sep 17 00:00:00 2001 From: Minsu Kim <60283244+minsuking@users.noreply.github.com> Date: Sat, 6 Sep 2025 00:02:56 +0900 Subject: [PATCH 4/5] docs: add note about running tutorials directly in Colab notebooks Signed-off-by: Minsu Kim <60283244+minsuking@users.noreply.github.com> --- README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/README.md b/README.md index 9e3f8d0ac..bcf4062ef 100644 --- a/README.md +++ b/README.md @@ -82,6 +82,9 @@ python -u unet_training_array.py --max_epochs 2 --batch_size 1 --num_workers 2 If the logs show decreasing training loss and a Dice score, the setup is correct. +**Note:** In most cases, users can run MONAI tutorials directly in Colab notebooks without additional installation. +The steps above are mainly for resolving dependency conflicts when installing extra packages. + #### Data Some notebooks will require additional data. From 9e1b3c7a869d989c55db6a03ebe09a067a807a47 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Fri, 5 Sep 2025 15:03:54 +0000 Subject: [PATCH 5/5] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index bcf4062ef..e23db92d9 100644 --- a/README.md +++ b/README.md @@ -82,7 +82,7 @@ python -u unet_training_array.py --max_epochs 2 --batch_size 1 --num_workers 2 If the logs show decreasing training loss and a Dice score, the setup is correct. -**Note:** In most cases, users can run MONAI tutorials directly in Colab notebooks without additional installation. +**Note:** In most cases, users can run MONAI tutorials directly in Colab notebooks without additional installation. The steps above are mainly for resolving dependency conflicts when installing extra packages. #### Data