diff --git a/.github/workflows/basic-tests-linux.yml b/.github/workflows/basic-tests-linux.yml index 319dd9c..86636a3 100644 --- a/.github/workflows/basic-tests-linux.yml +++ b/.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 diff --git a/.github/workflows/basic-tests-macos.yml b/.github/workflows/basic-tests-macos.yml index 00578e5..02f1e66 100644 --- a/.github/workflows/basic-tests-macos.yml +++ b/.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 diff --git a/.github/workflows/basic-tests-old-pytorch.yml b/.github/workflows/basic-tests-old-pytorch.yml index 7f76fc9..ea6dc89 100644 --- a/.github/workflows/basic-tests-old-pytorch.yml +++ b/.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 diff --git a/.github/workflows/basic-tests-pytorch-rc.yml b/.github/workflows/basic-tests-pytorch-rc.yml index bc211f1..a073acf 100644 --- a/.github/workflows/basic-tests-pytorch-rc.yml +++ b/.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 diff --git a/.github/workflows/basic-tests-windows.yml b/.github/workflows/basic-tests-windows.yml index f286156..43efbd7 100644 --- a/.github/workflows/basic-tests-windows.yml +++ b/.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 \ No newline at end of file diff --git a/.github/workflows/check-links.yml b/.github/workflows/check-links.yml index 6854d74..2e47b7d 100644 --- a/.github/workflows/check-links.yml +++ b/.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 diff --git a/.github/workflows/check-spelling-errors.yml b/.github/workflows/check-spelling-errors.yml index 37d76b5..2f5cbc8 100644 --- a/.github/workflows/check-spelling-errors.yml +++ b/.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} diff --git a/.github/workflows/pep8-linter.yml b/.github/workflows/pep8-linter.yml index c2a05dd..f632e31 100644 --- a/.github/workflows/pep8-linter.yml +++ b/.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 diff --git a/setup/01_optional-python-setup-preferences/README.md b/setup/01_optional-python-setup-preferences/README.md index 8574452..352fc54 100644 --- a/setup/01_optional-python-setup-preferences/README.md +++ b/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. + +No Python Found + +  +**Linux (Ubuntu/Debian)** + +```bash +sudo apt update +sudo apt install python3.10 python3.10-venv python3.10-dev +``` + +  +**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. + + +Python version + +  +**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. + + + +  + +## 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. + +  +**1. Install uv** + +```bash +pip install uv +``` + +  +**2. Create the virtual environment** + +```bash +uv venv --python=python3.10 +``` + +  +**3. Activate the virtual environment** + +```bash +source .venv/bin/activate +``` + +  +> [!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. + +Venv activated + +Optionally, you can deactivate the environment it by executing the command `deactivate`. + +Venv deactivated + +  +## 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 +``` + + +Uv install + +  +**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 +``` + +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. + +  +**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 +``` + +Uv install + + 

+  + +# 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. + + +  ## 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". -
-
- - +  ## 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 activate-env -
-
+  ## 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. -
-
- +  ## 3. Install new Python libraries @@ -84,9 +253,7 @@ You can also still use `pip` to install libraries. By default, `pip` should be l check-pip -
-
- +  ## 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 - +  ## 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. diff --git a/setup/02_installing-python-libraries/README.md b/setup/02_installing-python-libraries/README.md index 1a00cf8..7e96160 100644 --- a/setup/02_installing-python-libraries/README.md +++ b/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 -
-
- - +  ## Installing PyTorch PyTorch can be installed just like any other Python library or package using pip. For example: