From b0cdbd911941bdd596ac753fd33849ef83b1a841 Mon Sep 17 00:00:00 2001 From: Ego Joseph Oborakpororo <90655773+egojoseph@users.noreply.github.com> Date: Tue, 14 Jan 2025 17:05:08 +0100 Subject: [PATCH] Enhanced Installation Section in README.md (#35094) * Update README.md * Update README.md * Update README.md * Update README.md * Update README.md * Update README.md * Update README.md * Update README.md * Update README.md * Update README.md * Update README.md * Update README.md * Update README.md * Update README.md * Update README.md * Update README.md Enhanced installation section with troubleshooting, GPU setup, and OS-specific details. * Update README.md Enhanced installation section with troubleshooting, GPU setup, and OS-specific details. * Update installation.md Updated installation.md to include virtual environment and GPU setup instructions. * Update installation.md Updated installation.md to include virtual environment and GPU setup instructions. * Update installation.md Updated installation.md to include virtual environment, troubleshooting and GPU setup instructions. * Update installation.md * Update installation.md * Update installation.md * Update installation.md Updated installation.md to include virtual environment, troubleshooting functions and GPU setup instructions. * Update installation.md Updated installation.md to include virtual environment, troubleshooting functions and GPU setup instructions. * Update installation.md Updated installation.md to include virtual environment, troubleshooting functions and GPU setup instructions. * Update README.md Removed numbering from README.md. * Update README.md Removed unnecessary "a)" formatting as per maintainer feedback. * Update README.md Added blank lines around code snippets for better readability. * Update README.md Removed the line "b) Install a backend framework:" from README.md as per feedback. * Update README.md Simplified "For Windows:" to "Windows" in README.md as per feedback as well as "For macOS/Linux:" to "macOS/Linux" * Update README.md Removed unnecessary heading and retained valid code snippet. * Update README.md Removed unnecessary heading "d) Optional: Install from source for the latest updates" as per feedback. * Update README.md Removed "GPU Setup (Optional)" section to align with minimal design feedback. * Update installation.md Removed "Create and Activate a Virtual Environment" section from installation.md as per feedback. * Update installation.md Adjusted "Troubleshooting" to a second-level heading and added an introductory line as per feedback. * Update installation.md Updated troubleshooting section with simplified headings and formatted code blocks as per feedback. * Update installation.md Integrated GPU setup instructions into the "Install with pip" section for better content flow. * Update README.md Removed Troubleshooting section from README.md for minimalism as per maintainer feedback. --- README.md | 26 +++++++++++++++-- docs/source/en/installation.md | 52 +++++++++++++++++++++++++--------- 2 files changed, 61 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 42403f84b885..8ab5ceaf7e68 100644 --- a/README.md +++ b/README.md @@ -255,17 +255,37 @@ You should install πŸ€— Transformers in a [virtual environment](https://docs.pyt First, create a virtual environment with the version of Python you're going to use and activate it. -Then, you will need to install at least one of Flax, PyTorch, or TensorFlow. -Please refer to [TensorFlow installation page](https://www.tensorflow.org/install/), [PyTorch installation page](https://pytorch.org/get-started/locally/#start-locally) and/or [Flax](https://github.com/google/flax#quick-install) and [Jax](https://github.com/google/jax#installation) installation pages regarding the specific installation command for your platform. +**macOS/Linux** + +```python -m venv env +source env/bin/activate +``` + +**Windows** + +``` python -m venv env +env\Scripts\activate +``` + +To use πŸ€— Transformers, you must install at least one of Flax, PyTorch, or TensorFlow. Refer to the official installation guides for platform-specific commands: + +[TensorFlow installation page](https://www.tensorflow.org/install/), +[PyTorch installation page](https://pytorch.org/get-started/locally/#start-locally) and/or [Flax](https://github.com/google/flax#quick-install) and [Jax](https://github.com/google/jax#installation) When one of those backends has been installed, πŸ€— Transformers can be installed using pip as follows: -```bash +``` pip install transformers ``` If you'd like to play with the examples or need the bleeding edge of the code and can't wait for a new release, you must [install the library from source](https://huggingface.co/docs/transformers/installation#installing-from-source). +``` +git clone https://github.com/huggingface/transformers.git +cd transformers +pip install +``` + ### With conda πŸ€— Transformers can be installed using conda as follows: diff --git a/docs/source/en/installation.md b/docs/source/en/installation.md index af7c97ef3508..ae1f2101d749 100644 --- a/docs/source/en/installation.md +++ b/docs/source/en/installation.md @@ -32,27 +32,18 @@ Install πŸ€— Transformers for whichever deep learning library you're working wit You should install πŸ€— Transformers in a [virtual environment](https://docs.python.org/3/library/venv.html). If you're unfamiliar with Python virtual environments, take a look at this [guide](https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/). A virtual environment makes it easier to manage different projects, and avoid compatibility issues between dependencies. -Start by creating a virtual environment in your project directory: +Now you're ready to install πŸ€— Transformers with the following command: ```bash -python -m venv .env +pip install transformers ``` -Activate the virtual environment. On Linux and MacOs: +For GPU acceleration, install the appropriate CUDA drivers for [PyTorch](https://pytorch.org/get-started/locally) and TensorFlow(https://www.tensorflow.org/install/pip). -```bash -source .env/bin/activate -``` -Activate Virtual environment on Windows +Run the command below to check if your system detects an NVIDIA GPU. ```bash -.env/Scripts/activate -``` - -Now you're ready to install πŸ€— Transformers with the following command: - -```bash -pip install transformers +nvidia-smi ``` For CPU-support only, you can conveniently install πŸ€— Transformers and a deep learning library in one line. For example, install πŸ€— Transformers and PyTorch with: @@ -254,3 +245,36 @@ Once your file is downloaded and locally cached, specify it's local path to load See the [How to download files from the Hub](https://huggingface.co/docs/hub/how-to-downstream) section for more details on downloading files stored on the Hub. + +## Troubleshooting + +See below for some of the more common installation issues and how to resolve them. + +### Unsupported Python version + +Ensure you are using Python 3.9 or later. Run the command below to check your Python version. + +``` +python --version +``` + +### Missing dependencies + +Install all required dependencies by running the following command. Ensure you’re in the project directory before executing the command. + +``` +pip install -r requirements.txt +``` + +### Windows-specific + +If you encounter issues on Windows, you may need to activate Developer Mode. Navigate to Windows Settings > For Developers > Developer Mode. + +Alternatively, create and activate a virtual environment as shown below. + +``` +python -m venv env +.\env\Scripts\activate +``` + +