Installation

Installation#

Last updated: 12-03-2025

This guide provides instructions for setting up PyTorch on your local machine in an isolated environment. The installation process is streamlined using uv, which simplifies the management of Python versions, virtual environments, and dependencies. The guide covers the installation of Python 3.12, the setup of a project, the installation of required Python packages, and the installation of PyTorch.

Step 1: Install uv#

  • MacOS (using Homebrew)

    brew install uv

  • Windows (using PowerShell)

    powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

  • See the documentation for other installation methods.

After the installation, close and reopen the terminal to apply the changes, then confirm that uv is available by running the uv command. (If you are working in Visual Studio Code, you need to restart the editor as well.)

Step 2: Install Python 3.12#

If Python is already installed on your system, uv will detect and use it without configuration. The uv python list command (guide) allows you to see both the installed and the available Python versions.

uv python list

You can install Python using the uv python install command (guide). PyTorch requires Python 3.12 (at the time of writing this guide), which you can install as follows.

uv python install 3.12

Verify the Python installation using the command below.

uv python list --only-installed

Step 3: Set up a project#

Create a new folder where you want to store your project files. Navigate to the project directory in the terminal. Then, initialize a project using the init command (guide) with the desired Python version.

uv init --python 3.12

The command will create the following files in the project directory.

  • pyproject.toml: A configuration file for the project.

  • .python-version: Specifies the Python version for the project.

  • README.md: An empty markdown file for project documentation.

  • main.py: A sample Python script that prints “Hello world”.

Run the sample script to verify that the project is set up correctly.

uv run main.py

The first time you run a project command, uv will create a virtual environment and a uv.lock file in the project directory. The complete project structure will look like this.

.
├── .venv
│   ├── bin
│   ├── lib
│   └── pyvenv.cfg
├── .python-version
├── README.md
├── main.py
├── pyproject.toml
└── uv.lock

You may delete the main.py file at this point.

Version Control#

The project configuration (pyproject.toml) and the lockfile (uv.lock) should be included in version control to ensure that the project can be reproduced on other machines. The virtual environment (.venv) should be excluded from version control, as it is automatically created and managed by uv.

Step 4: Install dependencies#

The pyproject.toml contains metadata about your project. You will use this file to specify dependencies and other details about the project. You can edit this file manually, but it’s recommended to use uv commands to manage dependencies, as they also update the lockfile and the project environment.

  • uv add <PACKAGE> - Add a dependency to the project.

  • uv remove <PACKAGE> - Remove a dependency from the project.

  • uv lock --upgrade-package <PACKAGE> - Upgrade a package to the latest compatible version, while keeping the rest of the lockfile intact.

The following command adds the dependencies for a typical deep learning project in computer vision.

uv add numpy matplotlib scikit-learn notebook opencv-python gdown tqdm

Step 5: Install PyTorch#

PyTorch provides pre-built binaries for various platforms and accelerators, but they are published to different package indexes than the default PyPI. As such, the project configuration will vary depending on both the platforms you need to support and the accelerators you want to enable. (For more information on this topic, the uv documentation provides a detailed installation guide.)

Windows (CPU only) - MacOS ARM#

PyTorch can be installed from PyPI, which hosts CPU-only wheels for Windows, and MPS-accelerated wheels for MacOS with ARM processor. In this case, you simply add PyTorch and TorchVision to the project like any other package.

uv add torch torchvision

Windows (with NVIDIA GPU)#

PyTorch can be also installed from a custom package index that hosts CUDA-accelerated wheels for Windows. In this case, you need to specify the index in the project configuration.

  • Open the pyproject.toml file and add the following lines.

    # On Windows, torch and torchvision are fetched from a custom index 
# The custom index is referenced by the name "pytorch-cu126" in this config
[tool.uv.sources]
torch = [
  { index = "pytorch-cu126", marker = "sys_platform == 'win32'" },
]
torchvision = [
  { index = "pytorch-cu126", marker = "sys_platform == 'win32'" },
]

# Defining the custom index "pytorch-cu126"
[[tool.uv.index]]
name = "pytorch-cu126"
url = "https://download.pytorch.org/whl/cu126"
explicit = true

  • Add PyTorch and TorchVision to the project.

    uv add torch torchvision

  • Install CUDA Toolkit 12.6.

MacOS x86#

Unfortunately, PyTorch no longer provides pre-built binaries for MacOS x86. You have two options to install PyTorch on MacOS x86: either install an older version of PyTorch or compile from source.

Install an older version of PyTorch#

You can do this by declaring explicit support for non-latest platforms, since this often requires backtracking past the latest published versions of those packages.

  • Open the pyproject.toml file and add the following lines.

    [tool.uv]
required-environments = [
    "sys_platform == 'darwin' and platform_machine == 'x86_64'"
]

  • Add PyTorch and TorchVision to the project.

    uv add torch torchvision

This will install the last version of PyTorch that was released for MacOS x86. However, please note that this version may not be the latest release and may not include all the features and improvements available in the latest version, such as support for MPS acceleration.

Compile from source#

You can do this by building local wheels for PyTorch and TorchVision from the source code.

  • Compile the wheels for PyTorch and TorchVision (see the instructions below).

  • Add the wheels to the project using the uv pip install command. (Adjust the filenames according to the versions you built.)

    uv pip install torch-2.5.1-cp312-cp312-macosx_15_0_x86_64.whl
uv pip install torchvision-0.22.0a0+d3beb52-cp312-cp312-macosx_15_0_x86_64.whl

    Note that these commands will not add the packages to the project configuration.

This is the recommended option if you want to use the latest features and improvements available in PyTorch. However, this process can be complex and time-consuming.

Compile from source (MacOS x86)#

  • PyTorch no longer provides binaries for MacOS x86. You must compile from source by following these instructions.

    • Clone the git repository

    • Create a virtual environment and activate it

    • Install the dependencies

      pip install -r requirements.txt mkl-static mkl-include

    • Build the wheel

      env USE_CUDA=0 PYTORCH_BUILD_VERSION=2.5.1 PYTORCH_BUILD_NUMBER=0 python setup.py bdist_wheel

  • Torchvision no longer provides binaries for MacOS x86. You must compile from source by following these instructions.

    • Clone the git repository

    • Create a virtual environment and activate it

    • Install NumPy and PyTorch (from the wheel built previously)

      pip install numpy
pip install torch-2.5.1-cp312-cp312-macosx_15_0_x86_64.whl

    • Install ninja using Homebrew

      brew install ninja

    • Build the wheel

      MACOSX_DEPLOYMENT_TARGET=10.9 CC=clang CXX=clang++ FORCE_MPS=1 python setup.py bdist_wheel
Contents