From 61ca01c7c541542a3b40697f4f44ce7377d96ea4 Mon Sep 17 00:00:00 2001 From: rasbt Date: Sat, 15 Feb 2025 20:53:26 -0600 Subject: [PATCH] cosmetics --- .../README.md | 38 +++++++++---------- .../native-uv.md | 22 +++++------ 2 files changed, 29 insertions(+), 31 deletions(-) diff --git a/setup/01_optional-python-setup-preferences/README.md b/setup/01_optional-python-setup-preferences/README.md index 522115c..50ec899 100644 --- a/setup/01_optional-python-setup-preferences/README.md +++ b/setup/01_optional-python-setup-preferences/README.md @@ -2,7 +2,7 @@ -There are several ways to install Python and set up your computing environment. Here, I share my personal preferences. +There are several ways to install Python and set up your computing environment. Here, I share my personal preferences. 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. @@ -18,9 +18,9 @@ This section guides you through the Python setup and package installation proced   > [!NOTE] -> There are alternative ways to install Python and use `uv`. For example, you can install Python directly via `uv` and use `uv add` instead of `uv pip install` for faster package management. +> There are alternative ways to install Python and use `uv`. For example, you can install Python directly via `uv` and use `uv add` instead of `uv pip install` for faster package management. > -> If you prefer the native `uv` commands, refer to the [./native-uv.md tutorial](./native-uv.md). I also recommend checking the official [`uv` documentation](https://docs.astral.sh/uv/). +> If you prefer the native `uv` commands, refer to the [./native-uv.md tutorial](./native-uv.md). I also recommend checking the official [`uv` documentation](https://docs.astral.sh/uv/). > > While `uv add` offers speed advantages, I find `uv pip` slightly more user-friendly, making it a good starting point for beginners. However, if you're new to Python package management, the native `uv` interface is also a great way to learn. @@ -30,23 +30,24 @@ This section guides you through the Python setup and package installation proced   ## 1. Install Python (if not installed) +If you haven't manually installed Python on your system before, I highly recommend doing so. This helps prevent potential conflicts with your operating system's built-in Python installation, which could lead to issues. -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: +However, even if you have installed Python on your system before, 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. +If it returns 3.10 or newer, no further action is required.   -> [!NOTE] +> [!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 @@ -54,7 +55,7 @@ sudo apt update sudo apt install python3.10 python3.10-venv python3.10-dev ``` -  +
**macOS** If you use Homebrew, install Python with: @@ -70,14 +71,11 @@ I recommend installing a Python version that is at least two versions older than 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. @@ -88,21 +86,21 @@ I recommend installing a Python version that is at least 2 versions older than t 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 @@ -126,7 +124,7 @@ Optionally, you can deactivate the environment it by executing the command `deac   ## 3. Install packages -After activating your virtual environment, you can install Python packages using `uv`. For example: +After activating your virtual environment, you can install Python packages using `uv`. For example: ```bash uv pip install packaging @@ -147,12 +145,12 @@ uv pip install -U -r https://raw.githubusercontent.com/rasbt/LLMs-from-scratch/r 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: +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 @@ -170,7 +168,7 @@ uv pip install packagename 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: @@ -190,7 +188,7 @@ jupyterlab -This section guides you through the Python setup and package installation procedure 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. diff --git a/setup/01_optional-python-setup-preferences/native-uv.md b/setup/01_optional-python-setup-preferences/native-uv.md index 7a07a6c..b60d330 100644 --- a/setup/01_optional-python-setup-preferences/native-uv.md +++ b/setup/01_optional-python-setup-preferences/native-uv.md @@ -2,7 +2,7 @@ This tutorial is an alternative to *Option 1: Using uv* in the [README.md](./README.md) document for those who prefer `uv`'s native commands over the `uv pip` interface. While `uv pip` is faster than pure `pip`, `uv`'s native interface is even faster than `uv pip` as it has less overhead and doesn't have to handle legacy support for PyPy package dependency management. -Otherwise, similar to *Option 1: Using uv* in the [README.md](./README.md) , this section guides you through the Python setup and package installation procedure using `uv`. +Otherwise, similar to *Option 1: Using uv* in the [README.md](./README.md) , 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. @@ -12,7 +12,7 @@ In this tutorial, I am using a computer running macOS, but this workflow is simi Uv can be installed as follows, depending on your operating system. -  +
**macOS and Linux** ```bash @@ -25,7 +25,7 @@ or wget -qO- https://astral.sh/uv/install.sh | sh ``` -  +
**Windows** ```bash @@ -47,7 +47,7 @@ uv python install 3.10 ```   -> [!NOTE] +> [!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. You can find out the most recent Python version by visiting [python.org](https://www.python.org/downloads/).   @@ -74,7 +74,7 @@ uv add packaging Alternatively, you can still install the dependencies directly from the repository using `uv pip install`. Note that this requires creating and activating the virtual environment manually: -  +
**1. Create a new virtual environment** Run the following command to manually create a new virtual environment, which will be saved via a new `.venv` subfolder: @@ -83,7 +83,7 @@ Run the following command to manually create a new virtual environment, which wi uv venv --python=python3.10 ``` -  +
**2. Activate virtual environment** Next, we need to activate this new virtual environment. @@ -100,7 +100,7 @@ On Windows (PowerShell): .venv\Scripts\activate ``` -  +
**3. Install dependencies** Finally, we can install dependencies from a remote location using the `uv pip` interface: @@ -114,12 +114,12 @@ uv pip install -U -r https://raw.githubusercontent.com/rasbt/LLMs-from-scratch/r   ## 4. Run Python code -  +
**Finalizing the setup** Your environment should now be ready to run the code in the repository. -Optionally, you can run an environment check by executing the `python_environment_check.py` script in this repository: +Optionally, you can run an environment check by executing the `python_environment_check.py` script in this repository: ```bash uv run python setup/02_installing-python-libraries/python_environment_check.py @@ -131,7 +131,7 @@ uv run python setup/02_installing-python-libraries/python_environment_check.py -Or, if you don't want to type `uv run python` ever time you execute code, manually activate the virtual environment first. +Or, if you don't want to type `uv run python` ever time you execute code, manually activate the virtual environment first. On macOS/Linux: @@ -152,7 +152,7 @@ Then, run: python setup/02_installing-python-libraries/python_environment_check.py ``` -  +
**Launching JupyterLab** You can launch a JupyterLab instance via: