[examples] add check_min_version (#1550)

* add check_min_version for examples

* move __version__ to the top

* Apply suggestions from code review

Co-authored-by: Pedro Cuenca <pedro@huggingface.co>

* fix comment

* fix error_message

* adapt the install message

Co-authored-by: Pedro Cuenca <pedro@huggingface.co>

examples/dreambooth/README.md

@@ -9,8 +9,18 @@ The `train_dreambooth.py` script shows how to implement the training procedure a
 
 Before running the scripts, make sure to install the library's training dependencies:
 
+**Important**
+
+To make sure you can successfully run the latest versions of the example scripts, we highly recommend **installing from source** and keeping the install up to date as we update the example scripts frequently and install some example-specific requirements. To do this, execute the following steps in a new virtual environment:
 ```bash
-pip install -U -r requirements.txt
+git clone https://github.com/huggingface/diffusers
+cd diffusers
+pip install -e .
+```
+
+Then cd in the example folder and run
+```bash
+pip install -r requirements.txt
 ```
 
 And initialize an [🤗Accelerate](https://github.com/huggingface/accelerate/) environment with:

examples/dreambooth/requirements.txt

@@ -1,4 +1,3 @@
-diffusers>==0.5.0
 accelerate
 torchvision
 transformers>=4.21.0

examples/dreambooth/requirements_flax.txt

@@ -1,4 +1,3 @@
-diffusers>==0.5.1
 transformers>=4.21.0
 flax
 optax

examples/dreambooth/train_dreambooth.py

@@ -16,6 +16,7 @@ from accelerate.logging import get_logger
 from accelerate.utils import set_seed
 from diffusers import AutoencoderKL, DDPMScheduler, DiffusionPipeline, UNet2DConditionModel
 from diffusers.optimization import get_scheduler
+from diffusers.utils import check_min_version
 from huggingface_hub import HfFolder, Repository, whoami
 from PIL import Image
 from torchvision import transforms
@@ -23,6 +24,9 @@ from tqdm.auto import tqdm
 from transformers import AutoTokenizer, PretrainedConfig
 
 
+# Will error if the minimal version of diffusers is not installed. Remove at your own risks.
+check_min_version("0.10.0.dev0")
+
 logger = get_logger(__name__)
 
 

examples/dreambooth/train_dreambooth_flax.py

@@ -23,6 +23,7 @@ from diffusers import (
     FlaxUNet2DConditionModel,
 )
 from diffusers.pipelines.stable_diffusion import FlaxStableDiffusionSafetyChecker
+from diffusers.utils import check_min_version
 from flax import jax_utils
 from flax.training import train_state
 from flax.training.common_utils import shard
@@ -33,6 +34,9 @@ from tqdm.auto import tqdm
 from transformers import CLIPFeatureExtractor, CLIPTokenizer, FlaxCLIPTextModel, set_seed
 
 
+# Will error if the minimal version of diffusers is not installed. Remove at your own risks.
+check_min_version("0.10.0.dev0")
+
 logger = logging.getLogger(__name__)
 
 

examples/research_projects/dreambooth_inpaint/train_dreambooth_inpaint.py

@@ -24,6 +24,7 @@ from diffusers import (
     UNet2DConditionModel,
 )
 from diffusers.optimization import get_scheduler
+from diffusers.utils import check_min_version
 from huggingface_hub import HfFolder, Repository, whoami
 from PIL import Image, ImageDraw
 from torchvision import transforms
@@ -31,6 +32,9 @@ from tqdm.auto import tqdm
 from transformers import CLIPTextModel, CLIPTokenizer
 
 
+# Will error if the minimal version of diffusers is not installed. Remove at your own risks.
+check_min_version("0.10.0.dev0")
+
 logger = get_logger(__name__)
 
 

examples/text_to_image/README.md

@@ -12,9 +12,18 @@ ___This script is experimental. The script fine-tunes the whole model and often
 
 Before running the scripts, make sure to install the library's training dependencies:
 
+**Important**
+
+To make sure you can successfully run the latest versions of the example scripts, we highly recommend **installing from source** and keeping the install up to date as we update the example scripts frequently and install some example-specific requirements. To do this, execute the following steps in a new virtual environment:
 ```bash
-pip install "git+https://github.com/huggingface/diffusers.git#egg=diffusers[training]"
-pip install -U -r requirements.txt
+git clone https://github.com/huggingface/diffusers
+cd diffusers
+pip install .
+```
+
+Then cd in the example folder  and run
+```bash
+pip install -r requirements.txt
 ```
 
 And initialize an [🤗Accelerate](https://github.com/huggingface/accelerate/) environment with:

examples/text_to_image/requirements.txt

@@ -1,7 +1,7 @@
-diffusers==0.4.1
 accelerate
 torchvision
 transformers>=4.21.0
+datasets
 ftfy
 tensorboard
 modelcards

examples/text_to_image/requirements_flax.txt

@@ -1,5 +1,5 @@
-diffusers>==0.5.1
 transformers>=4.21.0
+datasets
 flax
 optax
 torch

examples/text_to_image/train_text_to_image.py

@@ -17,12 +17,16 @@ from accelerate.utils import set_seed
 from datasets import load_dataset
 from diffusers import AutoencoderKL, DDPMScheduler, StableDiffusionPipeline, UNet2DConditionModel
 from diffusers.optimization import get_scheduler
+from diffusers.utils import check_min_version
 from huggingface_hub import HfFolder, Repository, whoami
 from torchvision import transforms
 from tqdm.auto import tqdm
 from transformers import CLIPTextModel, CLIPTokenizer
 
 
+# Will error if the minimal version of diffusers is not installed. Remove at your own risks.
+check_min_version("0.10.0.dev0")
+
 logger = get_logger(__name__)
 
 

examples/text_to_image/train_text_to_image_flax.py

@@ -23,6 +23,7 @@ from diffusers import (
     FlaxUNet2DConditionModel,
 )
 from diffusers.pipelines.stable_diffusion import FlaxStableDiffusionSafetyChecker
+from diffusers.utils import check_min_version
 from flax import jax_utils
 from flax.training import train_state
 from flax.training.common_utils import shard
@@ -32,6 +33,9 @@ from tqdm.auto import tqdm
 from transformers import CLIPFeatureExtractor, CLIPTokenizer, FlaxCLIPTextModel, set_seed
 
 
+# Will error if the minimal version of diffusers is not installed. Remove at your own risks.
+check_min_version("0.10.0.dev0")
+
 logger = logging.getLogger(__name__)
 
 

examples/textual_inversion/README.md

@@ -16,8 +16,18 @@ Colab for inference
 
 Before running the scripts, make sure to install the library's training dependencies:
 
+**Important**
+
+To make sure you can successfully run the latest versions of the example scripts, we highly recommend **installing from source** and keeping the install up to date as we update the example scripts frequently and install some example-specific requirements. To do this, execute the following steps in a new virtual environment:
 ```bash
-pip install diffusers"[training]" accelerate "transformers>=4.21.0"
+git clone https://github.com/huggingface/diffusers
+cd diffusers
+pip install .
+```
+
+Then cd in the example folder  and run
+```bash
+pip install -r requirements.txt
 ```
 
 And initialize an [🤗Accelerate](https://github.com/huggingface/accelerate/) environment with:

examples/textual_inversion/requirements.txt

@@ -1,3 +1,6 @@
 accelerate
 torchvision
 transformers>=4.21.0
+ftfy
+tensorboard
+modelcards

examples/textual_inversion/requirements_flax.txt

@@ -1,4 +1,3 @@
-diffusers>==0.5.1
 transformers>=4.21.0
 flax
 optax

examples/textual_inversion/textual_inversion.py

@@ -19,6 +19,7 @@ from accelerate.utils import set_seed
 from diffusers import AutoencoderKL, DDPMScheduler, PNDMScheduler, StableDiffusionPipeline, UNet2DConditionModel
 from diffusers.optimization import get_scheduler
 from diffusers.pipelines.stable_diffusion import StableDiffusionSafetyChecker
+from diffusers.utils import check_min_version
 from huggingface_hub import HfFolder, Repository, whoami
 
 # TODO: remove and import from diffusers.utils when the new version of diffusers is released
@@ -48,6 +49,10 @@ else:
 # ------------------------------------------------------------------------------
 
 
+# Will error if the minimal version of diffusers is not installed. Remove at your own risks.
+check_min_version("0.10.0.dev0")
+
+
 logger = get_logger(__name__)
 
 

examples/textual_inversion/textual_inversion_flax.py

@@ -24,6 +24,7 @@ from diffusers import (
     FlaxUNet2DConditionModel,
 )
 from diffusers.pipelines.stable_diffusion import FlaxStableDiffusionSafetyChecker
+from diffusers.utils import check_min_version
 from flax import jax_utils
 from flax.training import train_state
 from flax.training.common_utils import shard
@@ -55,6 +56,9 @@ else:
     }
 # ------------------------------------------------------------------------------
 
+# Will error if the minimal version of diffusers is not installed. Remove at your own risks.
+check_min_version("0.10.0.dev0")
+
 logger = logging.getLogger(__name__)
 
 

examples/unconditional_image_generation/README.md

@@ -6,10 +6,21 @@ Creating a training image set is [described in a different document](https://hug
 
 Before running the scripts, make sure to install the library's training dependencies:
 
+**Important**
+
+To make sure you can successfully run the latest versions of the example scripts, we highly recommend **installing from source** and keeping the install up to date as we update the example scripts frequently and install some example-specific requirements. To do this, execute the following steps in a new virtual environment:
 ```bash
-pip install diffusers[training] accelerate datasets tensorboard
+git clone https://github.com/huggingface/diffusers
+cd diffusers
+pip install .
 ```
 
+Then cd in the example folder  and run
+```bash
+pip install -r requirements.txt
+```
+
+
 And initialize an [🤗Accelerate](https://github.com/huggingface/accelerate/) environment with:
 
 ```bash

examples/unconditional_image_generation/train_unconditional.py

@@ -11,11 +11,11 @@ import torch.nn.functional as F
 from accelerate import Accelerator
 from accelerate.logging import get_logger
 from datasets import load_dataset
-from diffusers import DDPMPipeline, DDPMScheduler, UNet2DModel, __version__
+from diffusers import DDPMPipeline, DDPMScheduler, UNet2DModel
 from diffusers.optimization import get_scheduler
 from diffusers.training_utils import EMAModel
+from diffusers.utils import check_min_version
 from huggingface_hub import HfFolder, Repository, whoami
-from packaging import version
 from torchvision.transforms import (
     CenterCrop,
     Compose,
@@ -28,8 +28,11 @@ from torchvision.transforms import (
 from tqdm.auto import tqdm
 
 
+# Will error if the minimal version of diffusers is not installed. Remove at your own risks.
+check_min_version("0.10.0.dev0")
+
+
 logger = get_logger(__name__)
-diffusers_version = version.parse(version.parse(__version__).base_version)
 
 
 def _extract_into_tensor(arr, timesteps, broadcast_shape):

examples/unconditional_image_generation/train_unconditional_ort.py

@@ -13,6 +13,7 @@ from datasets import load_dataset
 from diffusers import DDPMPipeline, DDPMScheduler, UNet2DModel
 from diffusers.optimization import get_scheduler
 from diffusers.training_utils import EMAModel
+from diffusers.utils import check_min_version
 from huggingface_hub import HfFolder, Repository, whoami
 from onnxruntime.training.ortmodule import ORTModule
 from torchvision.transforms import (
@@ -27,6 +28,9 @@ from torchvision.transforms import (
 from tqdm.auto import tqdm
 
 
+# Will error if the minimal version of diffusers is not installed. Remove at your own risks.
+check_min_version("0.10.0.dev0")
+
 logger = get_logger(__name__)
 
 

src/diffusers/__init__.py

@@ -1,3 +1,7 @@
+__version__ = "0.10.0.dev0"
+
+from .configuration_utils import ConfigMixin
+from .onnx_utils import OnnxRuntimeModel
 from .utils import (
     is_flax_available,
     is_inflect_available,
@@ -6,16 +10,10 @@ from .utils import (
     is_torch_available,
     is_transformers_available,
     is_unidecode_available,
+    logging,
 )
 
 
-__version__ = "0.10.0.dev0"
-
-from .configuration_utils import ConfigMixin
-from .onnx_utils import OnnxRuntimeModel
-from .utils import logging
-
-
 if is_torch_available():
     from .modeling_utils import ModelMixin
     from .models import AutoencoderKL, Transformer2DModel, UNet1DModel, UNet2DConditionModel, UNet2DModel, VQModel

src/diffusers/utils/__init__.py

@@ -15,6 +15,9 @@
 
 import os
 
+from packaging import version
+
+from .. import __version__
 from .deprecation_utils import deprecate
 from .import_utils import (
     ENV_VARS_TRUE_AND_AUTO_VALUES,
@@ -88,3 +91,16 @@ _COMPATIBLE_STABLE_DIFFUSION_SCHEDULERS = [
     "EulerAncestralDiscreteScheduler",
     "DPMSolverMultistepScheduler",
 ]
+
+
+def check_min_version(min_version):
+    if version.parse(__version__) < version.parse(min_version):
+        if "dev" in min_version:
+            error_message = (
+                "This example requires a source install from HuggingFace diffusers (see "
+                "`https://huggingface.co/docs/diffusers/installation#install-from-source`),"
+            )
+        else:
+            error_message = f"This example requires a minimum version of {min_version},"
+        error_message += f" but the version found is {__version__}.\n"
+        raise ImportError(error_message)