Switch from pip to uv (#529)

* Replace pip by more modern uv

* uv tests

* update yaml

* update yaml

* update yaml

* update flake8

* update windows commands

* fix windows test

* windows fix

* windows fix

* windows fix

* windows fix

* windows fix

* windows fix

* windows fix

* windows fix

* windows fix

* windows fix

.github/workflows/basic-tests-linux.yml

@@ -33,12 +33,17 @@ jobs:
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        pip install pytest nbval
-        if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
-        pip install -r ch05/07_gpt_to_llama/tests/test-requirements-extra.txt
+        pip install uv
+        uv venv --python=python3.10
+        source .venv/bin/activate
+        uv pip install pytest nbval
+        if [ -f requirements.txt ]; then uv pip install -r requirements.txt; fi
+        uv pip install -r ch05/07_gpt_to_llama/tests/test-requirements-extra.txt
+        uv pip install pytest
 
     - name: Test Selected Python Scripts
       run: |
+        source .venv/bin/activate
         pytest setup/02_installing-python-libraries/tests.py
         pytest ch04/01_main-chapter-code/tests.py
         pytest ch05/01_main-chapter-code/tests.py
@@ -47,6 +52,7 @@ jobs:
 
     - name: Validate Selected Jupyter Notebooks
       run: |
+        source .venv/bin/activate
         pytest --nbval ch02/01_main-chapter-code/dataloader.ipynb
         pytest --nbval ch03/01_main-chapter-code/multihead-attention.ipynb
         pytest --nbval ch02/04_bonus_dataloader-intuition/dataloader-intuition.ipynb

.github/workflows/basic-tests-macos.yml

@@ -33,12 +33,17 @@ jobs:
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        pip install pytest nbval
-        if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
-        pip install -r ch05/07_gpt_to_llama/tests/test-requirements-extra.txt
+        pip install uv
+        uv venv --python=python3.10
+        source .venv/bin/activate
+        uv pip install pytest nbval
+        if [ -f requirements.txt ]; then uv pip install -r requirements.txt; fi
+        uv pip install -r ch05/07_gpt_to_llama/tests/test-requirements-extra.txt
+        uv pip install pytest
 
     - name: Test Selected Python Scripts
       run: |
+        source .venv/bin/activate
         pytest setup/02_installing-python-libraries/tests.py
         pytest ch04/01_main-chapter-code/tests.py
         pytest ch05/01_main-chapter-code/tests.py
@@ -47,6 +52,7 @@ jobs:
 
     - name: Validate Selected Jupyter Notebooks
       run: |
+        source .venv/bin/activate
         pytest --nbval ch02/01_main-chapter-code/dataloader.ipynb
         pytest --nbval ch03/01_main-chapter-code/multihead-attention.ipynb
         pytest --nbval ch02/04_bonus_dataloader-intuition/dataloader-intuition.ipynb

.github/workflows/basic-tests-old-pytorch.yml

@@ -36,13 +36,18 @@ jobs:
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip setuptools wheel
-        pip install pytest nbval
-        pip install torch==${{ matrix.pytorch-version }}
-        pip install -r requirements.txt
-        pip install -r ch05/07_gpt_to_llama/tests/test-requirements-extra.txt
+        pip install uv
+        uv venv --python=python3.10
+        source .venv/bin/activate
+        uv pip install pytest nbval
+        uv pip install torch==${{ matrix.pytorch-version }}
+        uv pip install -r requirements.txt
+        uv pip install -r ch05/07_gpt_to_llama/tests/test-requirements-extra.txt
+        uv pip install pytest
 
     - name: Test Selected Python Scripts
       run: |
+        source .venv/bin/activate
         pytest setup/02_installing-python-libraries/tests.py
         pytest ch04/01_main-chapter-code/tests.py
         pytest ch05/01_main-chapter-code/tests.py
@@ -51,6 +56,7 @@ jobs:
 
     - name: Validate Selected Jupyter Notebooks
       run: |
+        source .venv/bin/activate
         pytest --nbval ch02/01_main-chapter-code/dataloader.ipynb
         pytest --nbval ch03/01_main-chapter-code/multihead-attention.ipynb
         pytest --nbval ch02/04_bonus_dataloader-intuition/dataloader-intuition.ipynb

.github/workflows/basic-tests-pytorch-rc.yml

@@ -32,13 +32,18 @@ jobs:
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        pip install pytest nbval
-        if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
-        pip install -r ch05/07_gpt_to_llama/tests/test-requirements-extra.txt
-        pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/cpu
+        pip install uv
+        uv venv --python=python3.10
+        source .venv/bin/activate
+        uv pip install pytest nbval
+        if [ -f requirements.txt ]; then uv pip install -r requirements.txt; fi
+        uv pip install -r ch05/07_gpt_to_llama/tests/test-requirements-extra.txt
+        uv pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/cpu
+        uv pip install pytest
 
     - name: Test Selected Python Scripts
       run: |
+        source .venv/bin/activate
         pytest setup/02_installing-python-libraries/tests.py
         pytest ch04/01_main-chapter-code/tests.py
         pytest ch05/01_main-chapter-code/tests.py
@@ -47,6 +52,7 @@ jobs:
 
     - name: Validate Selected Jupyter Notebooks
       run: |
+        source .venv/bin/activate
         pytest --nbval ch02/01_main-chapter-code/dataloader.ipynb
         pytest --nbval ch03/01_main-chapter-code/multihead-attention.ipynb
         pytest --nbval ch02/04_bonus_dataloader-intuition/dataloader-intuition.ipynb

.github/workflows/basic-tests-windows.yml

@@ -54,4 +54,4 @@ jobs:
         run: |
           pytest --nbval ch02/01_main-chapter-code/dataloader.ipynb
           pytest --nbval ch03/01_main-chapter-code/multihead-attention.ipynb
-          pytest --nbval ch02/04_bonus_dataloader-intuition/dataloader-intuition.ipynb
+          pytest --nbval ch02/04_bonus_dataloader-intuition/dataloader-intuition.ipynb

.github/workflows/check-links.yml

@@ -23,12 +23,17 @@ jobs:
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        pip install pytest pytest-check-links
+        pip install uv
+        uv venv --python=python3.10
+        source .venv/bin/activate
+        uv pip install pytest pytest-check-links
         # Current version of retry doesn't work well if there are broken non-URL links
         # pip install pytest pytest-check-links pytest-retry
+        uv pip install pytest pytest-check-links
 
     - name: Check links
       run: |
+        source .venv/bin/activate
         pytest --check-links ./ --check-links-ignore "https://platform.openai.com/*" --check-links-ignore "https://openai.com/*" --check-links-ignore "https://arena.lmsys.org" --check-links-ignore https://unsloth.ai/blog/gradient --check-links-ignore "https://www.reddit.com/r/*" --check-links-ignore "https://code.visualstudio.com/*" --check-links-ignore https://arxiv.org/* --check-links-ignore "https://ai.stanford.edu/~amaas/data/sentiment/"
         # pytest --check-links ./ --check-links-ignore "https://platform.openai.com/*" --check-links-ignore "https://arena.lmsys.org" --retries 2 --retry-delay 5
 

.github/workflows/check-spelling-errors.yml

@@ -23,8 +23,12 @@ jobs:
       - name: Install codespell
         run: |
           python -m pip install --upgrade pip
-          pip install codespell
+          pip install uv
+          uv venv --python=python3.10
+          source .venv/bin/activate
+          uv pip install codespell
 
       - name: Run codespell
         run: |
+          source .venv/bin/activate
           codespell -L "ocassion,occassion,ot,te,tje" **/*.{txt,md,py,ipynb}

.github/workflows/pep8-linter.yml

@@ -16,6 +16,14 @@ jobs:
       with:
         python-version: '3.10'
     - name: Install flake8
-      run: pip install flake8
+      run: |
+        python -m pip install --upgrade pip
+        pip install uv
+        uv venv --python=python3.10
+        source .venv/bin/activate
+        uv pip install flake8
+
     - name: Run flake8 with exceptions
-      run: flake8 . --max-line-length=140 --ignore=W504,E402,E731,C406,E741,E722,E226
+      run: |
+        source .venv/bin/activate
+        flake8 . --max-line-length=140 --ignore=W504,E402,E731,C406,E741,E722,E226 --exclude .venv

setup/01_optional-python-setup-preferences/README.md

@@ -2,15 +2,190 @@
 
 
 
-There are several different ways you can install Python and set up your computing environment. Here, I am illustrating my personal preference.
+There are several ways to install Python and set up your computing environment. Here, I share my personal preferences. 
 
-(I am using computers running macOS, but this workflow is similar for Linux machines and may work for other operating systems as well.)
+I have been a long-time user of [Conda](https://anaconda.org/anaconda/conda) and [pip](https://pypi.org/project/pip/), but recently, the [uv](https://github.com/astral-sh/uv) package has gained significant traction as it provides a faster and more efficient way to install packages and resolve dependencies.
 
+I recommend starting with *Option 1: Using uv* as it is the more modern approach in 2025. If you encounter problems with *Option 1*, consider *Option 2: Option 2: Using Conda*.
 
+
+ 
+# Option 1: Using uv
+
+ 
+
+This section guides you through the Python setup and package installation procedure using `uv`. 
+
+In this tutorial, I am using a computer running macOS, but this workflow is similar for Linux machines and may work for other operating systems as well.
+
+
+
+## 1. Install Python (if not installed)
+
+First, check if you have a modern version of Python installed (I recommend 3.10 or newer) by executing the following code in the terminal:
+
+```bash
+python --version
+```
+If it returns 3.10 or newer, no further action is required. 
+
+> [!NOTE]  
+> I recommend installing a Python version that is at least 2 versions older than the most recent release to ensure PyTorch compatibility. For example, if the most recent version is Python 3.13, I recommend installing version 3.10 or 3.11.
+
+Otherwise, if Python is not installed or is an older version, you can install it for your operating system as described below.
+
+<img src="https://sebastianraschka.com/images/LLMs-from-scratch-images/setup/uv-setup/python-not-found.png" width="500" height="auto" alt="No Python Found">
+
+&nbsp;
+**Linux (Ubuntu/Debian)**
+
+```bash
+sudo apt update
+sudo apt install python3.10 python3.10-venv python3.10-dev
+```
+
+&nbsp;
+**macOS**
+
+If you use Homebrew, install Python with:
+
+```bash
+brew install python@3.10
+```
+
+Alternatively, download and run the installer from the official website: [https://www.python.org/downloads/](https://www.python.org/downloads/).
+
+I recommend installing a Python version that is at least two versions older than the latest release to ensure PyTorch compatibility.
+
+
+<img src="https://sebastianraschka.com/images/LLMs-from-scratch-images/setup/uv-setup/python-version.png" width="700" height="auto" alt="Python version">
+
+&nbsp;
+**Windows**
+
+Download and run the installer from the official website: [https://www.python.org/downloads/](https://www.python.org/downloads/).
+
+
+Obtain and execute the installer from the official website: https://www.python.org/downloads/.
+
+I recommend installing a Python version that is at least 2 versions older than the most recent release to ensure PyTorch compatibility. For example, if the most recent version is Python 3.13, I recommend installing version 3.10 or 3.11.
+
+
+
+&nbsp;
+
+## 2. Create a virtual environment
+
+I highly recommend installing Python packages in a separate virtual environment to avoid modifying system-wide packages that your OS may depend on. To create a virtual environment in the current folder, follow the three steps below.
+
+&nbsp;
+**1. Install uv**
+
+```bash
+pip install uv
+```
+
+&nbsp;
+**2. Create the virtual environment**
+
+```bash
+uv venv --python=python3.10
+```
+
+&nbsp;
+**3. Activate the virtual environment**
+
+```bash
+source .venv/bin/activate
+```
+
+&nbsp;
+> [!NOTE]
+> If you are using Windows, you may have to replace the command above by `source .venv/Scripts/activate`
+
+
+
+Note that you need to activate the virtual environment each time you start a new terminal session. For example, if you restart your terminal or computer and want to continue working on the project the next day, simply run source `.venv/bin/activate` in the project folder to reactivate your virtual environment.
+
+<img src="https://sebastianraschka.com/images/LLMs-from-scratch-images/setup/uv-setup/venv-activate-1.png" width="600" height="auto" alt="Venv activated">
+
+Optionally, you can deactivate the environment it by executing the command `deactivate`.
+
+<img src="https://sebastianraschka.com/images/LLMs-from-scratch-images/setup/uv-setup/venv-activate-2.png" width="800" height="auto" alt="Venv deactivated">
+
+&nbsp;
+## 3. Install packages
+
+After activating your virtual environment, you can install Python packages using `uv`. For example: 
+
+```bash
+uv pip install packaging
+```
+
+To install all required packages from a `requirements.txt` file (such as the one located at the top level of this GitHub repository) run the following command, assuming the file is in the same directory as your terminal session:
+
+```bash
+uv pip install -U -r requirements.txt
+```
+
+Alternatively, install the latest dependencies directly from the repository:
+
+```bash
+uv pip install -U -r https://raw.githubusercontent.com/rasbt/LLMs-from-scratch/refs/heads/main/requirements.txt
+```
+
+
+<img src="https://sebastianraschka.com/images/LLMs-from-scratch-images/setup/uv-setup/uv-install.png" width="700" height="auto" alt="Uv install">
+
+&nbsp;
+**Finalizing the setup**
+
+That’s it! Your environment should now be ready for running the code in the repository.
+
+Optionally, you can run an environment check by executing the `python_environment_check.py` script in this repostiory: 
+
+```bash
+python setup/02_installing-python-libraries/python_environment_check.py
+```
+
+<img src="https://sebastianraschka.com/images/LLMs-from-scratch-images/setup/uv-setup/env-check.png" width="700" height="auto" alt="Environment check">
+
+If you encounter any issues with specific packages, try reinstalling them using:
+
+```bash
+uv pip install packagename
+```
+
+(Here, `packagename` is a placeholder name that needs to be replaced with the package name you are having problems with.)
+
+If problems persist, consider [opening a discussion](https://github.com/rasbt/LLMs-from-scratch/discussions) on GitHub or working through the *Option 2: Using Conda* section below.
+
+&nbsp;
+**Start working with the code**
+
+Once everything is set up, you can start working with the code files. For instance, launch [JupyterLab](https://jupyterlab.readthedocs.io/en/latest/) by running:
+
+```bash
+jupyterlab
+```
+
+<img src="https://sebastianraschka.com/images/LLMs-from-scratch-images/setup/uv-setup/jupyter.png" width="900" height="auto" alt="Uv install">
+
+&nbsp;
 <br>
 <br>
+&nbsp;
+
+# Option 2: Using Conda
+
+
+
+This section guides you through the Python setup and package installation procedure using `uv`. 
+
+In this tutorial, I am using a computer running macOS, but this workflow is similar for Linux machines and may work for other operating systems as well.
 
 
+&nbsp;
 ## 1. Download and install Miniforge
 
 Download miniforge from the GitHub repository [here](https://github.com/conda-forge/miniforge).
@@ -32,10 +207,7 @@ where `Desktop/` is the folder where the Miniforge installer was downloaded to.
 Next, step through the download instructions, confirming with "Enter".
 
 
-<br>
-<br>
-
-
+&nbsp;
 ## 2. Create a new virtual environment
 
 After the installation was successfully completed, I recommend creating a new virtual environment called `LLMs`, which you can do by executing
@@ -56,16 +228,13 @@ conda activate LLMs
 
 <img src="https://sebastianraschka.com/images/LLMs-from-scratch-images/setup/01_optional-python-setup-preferences/activate-env.png" alt="activate-env" width="600px">
 
-<br>
-<br>
 
+&nbsp;
 ## Optional: styling your terminal
 
 If you want to style your terminal similar to mine so that you can see which virtual environment is active,  check out the [Oh My Zsh](https://github.com/ohmyzsh/ohmyzsh) project.
 
-<br>
-<br>
-
+&nbsp;
 ## 3. Install new Python libraries
 
 
@@ -84,9 +253,7 @@ You can also still use `pip` to install libraries. By default, `pip` should be l
 
 <img src="https://sebastianraschka.com/images/LLMs-from-scratch-images/setup/01_optional-python-setup-preferences/check-pip.png" alt="check-pip" width="600px">
 
-<br>
-<br>
-
+&nbsp;
 ## 4. Install PyTorch
 
 PyTorch can be installed just like any other Python library or package using pip. For example:
@@ -101,7 +268,7 @@ It's also highly recommended to consult the installation guide menu on the offic
 
 <img src="https://sebastianraschka.com/images/LLMs-from-scratch-images/setup/01_optional-python-setup-preferences/pytorch-installer.jpg" width="600px">
 
-
+&nbsp;
 ## 5. Installing Python packages and libraries used in this book
 
 Please refer to the [Installing Python packages and libraries used in this book](../02_installing-python-libraries/README.md) document for instructions on how to install the required libraries.

setup/02_installing-python-libraries/README.md

@@ -4,6 +4,13 @@ This document provides more information on double-checking your installed Python
 
 I used the following libraries listed [here](https://github.com/rasbt/LLMs-from-scratch/blob/main/requirements.txt) for this book. Newer versions of these libraries are likely compatible as well. However, if you experience any problems with the code, you can try these library versions as a fallback.
 
+
+
+> [!NOTE]
+> If you you are using `uv` as described in [Option 1: Using uv](../01_optional-python-setup-preferences/README.md), you can replace `pip` via `pip uv` in the commands below. For example, `pip install -r requirements.txt` becomes `uv pip install -r requirements.txt`
+
+
+
 To install these requirements most conveniently, you can use the `requirements.txt` file in the root directory for this code repository and execute the following command:
 
 ```bash
@@ -38,10 +45,7 @@ In this case, you may want to use `watermark` to check if you opened the Jupyter
 <img src="https://sebastianraschka.com/images/LLMs-from-scratch-images/setup/02_installing-python-libraries/watermark.jpg" width="350px">
 
 
-<br>
-<br>
-
-
+&nbsp;
 ## Installing PyTorch
 
 PyTorch can be installed just like any other Python library or package using pip. For example: