LLMs-from-scratch/setup/01_optional-python-setup-preferences/native-uv.md

# Native uv Python and package management

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.

The table below provides a comparison of the speeds of different dependency and package management approaches. The speed comparison specifically refers to package dependency resolution during installation, not the runtime performance of the installed packages. Note that package installation is a one-time process for this project, so it is reasonable to choose the preferred approach by overall convenience, not just installation speed.


| Command               | Speed Comparison |
|-----------------------|-----------------|
| `conda install <pkg>` | Slowest (Baseline) |
| `pip install <pkg>`   | 2-10× faster than above |
| `uv pip install <pkg>`| 5-10× faster than above |
| `uv add <pkg>`        | 2-5× faster than above |

This tutorial focuses on `uv add`.


Otherwise, similar to *Option 1: Using uv* in the [README.md](./README.md) , this tutorial 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. Install uv

Uv can be installed as follows, depending on your operating system.

<br>

**macOS and Linux**

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

or

```bash
wget -qO- https://astral.sh/uv/install.sh | sh
```

<br>

**Windows**

```bash
powershell -c "irm https://astral.sh/uv/install.ps1 | more"
```

&nbsp;

> [!NOTE]
> For more installation options, please refer to the official [uv documentation](https://docs.astral.sh/uv/getting-started/installation/#standalone-installer).

&nbsp;
## 2. Install Python

You can install Python using uv:

```bash
uv python install 3.10
```

&nbsp;
> [!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/).

&nbsp;
## 3. Install Python packages and dependencies

To install all required packages from a `pyproject.toml` 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 add . --dev
```

> [!NOTE]
> If you have problems with the following commands above due to certain dependencies (for example, if you are using Windows), you can always fall back to regular pip:
> `uv add pip`
> `uv run python -m pip install -U -r requirements.txt`


<img src="https://sebastianraschka.com/images/LLMs-from-scratch-images/setup/uv-setup/uv-add.png?1" width="700" height="auto" alt="Uv install">

Note that the `uv add` command above will create a separate virtual environment via the `.venv` subfolder. (In case you want to delete your virtual environment to start from scratch, you can simply delete the `.venv` folder.)

You can install new packages, that are not specified in the `pyproject.toml` via `uv add`, for example:

```bash
uv add packaging
```

And you can remove packages via `uv remove`, for example,	

```bash
uv remove packaging
```



&nbsp;
## 3. Run Python code

<br>

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:

```bash
uv run python setup/02_installing-python-libraries/python_environment_check.py
```



<img src="https://sebastianraschka.com/images/LLMs-from-scratch-images/setup/uv-setup/uv-run-check.png?1" width="700" height="auto" alt="Uv install">



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:

```bash
source .venv/bin/activate
```

On Windows (PowerShell):

```bash
.venv\Scripts\activate
```

Then, run:


```bash
python setup/02_installing-python-libraries/python_environment_check.py
```

<br>

**Launching JupyterLab**

You can launch a JupyterLab instance via:

```bash
uv run jupyter lab
```

**Skipping the `uv run` command**

If you find typing `uv run` cumbersome and want to run scripts via 

```bash
python script.py
```

and launch JupyterLab via 

```bash
juputer lab
```

instead, you can activated the environment manually.

On macOS/Linux:

```bash
source .venv/bin/activate
```

On Windows (PowerShell):

```bash
.venv\Scripts\activate
```


&nbsp;

## Optional: Manage virtual environments manually

Alternatively, you can still install the dependencies directly from the repository using `uv pip install`. But note that this doesn't record dependencies in a `uv.lock` file as `uv add` does. Also, it requires creating and activating the virtual environment manually:

<br>

**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:

```bash
uv venv --python=python3.10
```

<br>

**2. Activate virtual environment**

Next, we need to activate this new virtual environment.

On macOS/Linux:

```bash
source .venv/bin/activate
```

On Windows (PowerShell):

```bash
.venv\Scripts\activate
```

<br>

**3. Install dependencies**

Finally, we can install dependencies from a remote location using the `uv pip` interface:

```bash
uv pip install -U -r https://raw.githubusercontent.com/rasbt/LLMs-from-scratch/refs/heads/main/requirements.txt
```



---

Any questions? Please feel free to reach out in the [Discussion Forum](https://github.com/rasbt/LLMs-from-scratch/discussions).