Fix incorrect installation instructions (for issue #37476) #37640

Zephyr271828 · 2025-04-20T18:54:01Z

What does this PR do?

This PR is a proposed solution for issue #37476. Specifically, this PR modifies description in README.md, adds a requirements.txt file and an install.sh file:

README.md: change python version requirement from 3.9+ to 3.9-3.12; add feasible installation commands. These changes will also fix the transformers pypi page.

# venv
python -m venv .my-env
source .my-env/bin/activate
pip install "jax>=0.4.1,<=0.4.13"
pip install "optax>=0.0.8,<=0.1.4"
pip install "orbax-checkpoint==0.2.3"
pip install "torch>=2.1"
pip install "tensorflow>2.9,<2.16"
pip install "flax>=0.4.1,<=0.7.0"
pip install "accelerate>=0.26.0"

requirements.txt: listing the core requirements of the package as specified in setup.py. Note more variants of requirements.txt should be added, but I'm not sure how to do it. I would be grateful if you could give me some suggestions!
install.sh: a script that verifies python version, creates the virtual env, installs the core packages, and validates the installation with the quickstart example. The script closely follows the version requiremetns in setup.py, and has been tested and worked on my machine. If you encounter any bugs, please tell me so that I can fix accordingly.

Before submitting

This PR fixes a typo or improves the docs (you can dismiss the other checks if that's the case).
Did you read the contributor guideline,
Pull Request section?
Was this discussed/approved via a Github issue or the forum? Please add a link
to it if that's the case.
Did you make sure to update the documentation with your changes? Here are the
documentation guidelines, and
here are tips on formatting docstrings.
Did you write any new necessary tests?

Who can review?

Anyone in the community is free to review the PR once the tests have passed. Feel free to tag
members/contributors who may be interested in your PR.

… dev

…into time-strategy

…allation

…nto installation

github-actions · 2025-04-20T18:54:14Z

Hi 👋, thank you for opening this pull request! The pull request is converted to draft by default. The CI will be paused while the PR is in draft mode. When it is ready for review, please click the Ready for review button (at the bottom of the PR page). This will assign reviewers and trigger CI.

DarkTyger · 2025-04-21T04:46:59Z

README.md

 ## Installation

-Transformers works with Python 3.9+ [PyTorch](https://pytorch.org/get-started/locally/) 2.1+, [TensorFlow](https://www.tensorflow.org/install/pip) 2.6+, and [Flax](https://flax.readthedocs.io/en/latest/) 0.4.1+.
+Transformers works with Python 3.9-3.12 [PyTorch](https://pytorch.org/get-started/locally/) 2.1+, [TensorFlow](https://www.tensorflow.org/install/pip) 2.6+, and [Flax](https://flax.readthedocs.io/en/latest/) 0.4.1+.


The meaning behind the DRY principle is a bit deeper than "don't repeat yourself." Rather, DRY is a principle of software development aimed at reducing repetition of information likely to change. By documenting the versions in two places (README.md, requirements.txt file) the information has been repeated, which will inevitably lead to one or the other going stale.

Instead, keep the requirements inside of requirements.txt file and direct the reader to read that file, because it captures the same information.

The meaning behind the DRY principle is a bit deeper than "don't repeat yourself." Rather, DRY is a principle of software development aimed at reducing repetition of information likely to change. By documenting the versions in two places (README.md, requirements.txt file) the information has been repeated, which will inevitably lead to one or the other going stale.

Instead, keep the requirements inside of requirements.txt file and direct the reader to read that file, because it captures the same information.

Great suggestion! Will do that.

DarkTyger · 2025-04-21T04:49:07Z

README.md

 ## Installation

-Transformers works with Python 3.9+ [PyTorch](https://pytorch.org/get-started/locally/) 2.1+, [TensorFlow](https://www.tensorflow.org/install/pip) 2.6+, and [Flax](https://flax.readthedocs.io/en/latest/) 0.4.1+.
+Transformers works with Python 3.9-3.12 [PyTorch](https://pytorch.org/get-started/locally/) 2.1+, [TensorFlow](https://www.tensorflow.org/install/pip) 2.6+, and [Flax](https://flax.readthedocs.io/en/latest/) 0.4.1+.


Nit: Python 3.9 to 3.12 or Python 3.9 - 3.12

Note the space in the second, which will distinguish from potentially oddball versions (i.e., there is no version with the literal expression 3.9-3.12).

Nit: Python 3.9 to 3.12 or Python 3.9 - 3.12

Note the space in the second, which will distinguish from potentially oddball versions (i.e., there is no version with the literal expression 3.9-3.12).

Thanks, will modify this!

DarkTyger · 2025-04-21T04:54:33Z

requirements/install.sh

+
+# === Install Required Packages ===
+echo "Installing required packages..."
+pip install "jax>=0.4.1,<=0.4.13"


Why are these pip instructions different than the files listed inside the requirements.txt file? And why are the versions repeated all over the place? They're listed like 5 times, a quintuplication of information.

Is there a way to reference the requirements.txt file from the script?

Like xargs pip install < requirements.txt?

Why are these pip instructions different than the files listed inside the requirements.txt file? And why are the versions repeated all over the place? They're listed like 5 times, a quintuplication of information.

Is there a way to reference the requirements.txt file from the script?

Like xargs pip install < requirements.txt?

Referring to requirements.txt sounds more reasonable and I will do that, but I need to think about what to put in requirements.txt a bit more. Will ping you again if my revision is completed!

DarkTyger · 2025-04-21T04:55:46Z

requirements/requirements.txt

@@ -0,0 +1,10 @@
+filelock


I don't recall having to install most of these on my system. Did you spin up a base Arch (or Debian) image with a bare minimum install and see what's required to run?

I don't recall having to install most of these on my system. Did you spin up a base Arch (or Debian) image with a bare minimum install and see what's required to run?

Dear @DarkTyger, thank you so much for your detailed suggestions! I will try my best and keep polishing my PR until it can be merged.
As for requirements.txt, I was referring to setup.py and I believe the packages listed here are the prerequisites for installing the transformer packages. So I guess they should be included in the requirements.txt?

Dear @DarkTyger, after some further investigation of the issue, I think I may need some clarifications on what the fix should be like. Considering your suggestions in the issue:

fix python version requirements;

a requirements.txt file that people can download;

a shell script that can install and validate the requisite versions;

explicitly list all instructions that'll work for most people.

The first one is very reasonable and I will submit a fix soon.
However, I'm not quite sure if adding requirements.txt, installation script, or explicitly listing the instructions is necessary? I'm asking this question for 2 reasons:

setup.py may be sufficient for installation, and adding requirements.txt or installation script can be repetitive. I don't know what you mean by "work for most people"? It turns out using pip install "transformers[all]" or pip install .[all] installs all the required packages and the quickstart examples can be used immediately after running one of these 2 commands. Therefore, adding requirements.txt or installation script can be repetitive, violating the DRY principle you mentioned earlier.

In the examples folder, requirements files are provided for different use cases, but they are quite different from task to task so it's hard to determine what are the core packages to include. Moreover, the examples and their requirements are not maintained frequently. Maybe the repo is not designed to use requirements.txt for installation.

As for the packages you mentioned (torch, tensorflow, flax, accelerate, and transformers), I believe pip install transformers[all] is the command you want to try. You may refer to here.
Please correct me if I made anything wrong.

I'm not sure how else to put this; the documentation is incorrect.

Create a new virtual OS (or container) with latest Python.

Visit https://pypi.org/project/transformers

Follow the instructions as shown.

Expected

Instructions work.

Actual

pip install transformers fails (for a few reasons, including Python version and missing [all]).

Whether a script, a requirements.txt file, or an update to the documentation is the solution, wasn't really my point. My points are:

when drafting instructions, avoid repeating information that is likely to change; and

ensure the instructions are tested in a clean environment on supported platforms.

If following the instructions verbatim (and that's key) fails, then the instructions are wrong.

Aside, written instructions in README.md are hard to test automatically, which is why I recommended writing a script. If the instructions become "1. download script; 2. run script" then that can be tested within containerized environments. When problems are encountered, the script gets the fixes, and the automated test guards against regressions. This means the README.md needn't change to put in a fix because the requirements are captured programmatically.

Hi @DarkTyger sorry for the late reply. I just made a new version of the PR, and would be grateful if you could check if this version looks good to you.

I've looked over the changes briefly. They look much better!

Glad to hear that! Thank you for your suggestions!
@Rocketknight1 @ArthurZucker Could you please help check if this PR looks ok and consistent with the style of the repo?

Rocketknight1

Hi @Zephyr271828, I'm sorry for being late with this one, but I don't think we can accept this PR as-is, but we could accept some of the changes from it! I should have said something earlier, but there are a few issues:

We don't want to limit our Python version compatibility to remain compatible with Tensorflow. Right now our TF/JAX support is mostly in maintenance mode, and PyTorch is the primary framework of the library!
We don't want to add a separate install.sh script, especially since we don't need the Py<3.13 version check!

However, some of the changes here are useful, and we could keep them! I'll flag them in the comments.

Rocketknight1 · 2025-05-07T13:32:41Z

README.md

 ## Installation

-Transformers works with Python 3.9+ [PyTorch](https://pytorch.org/get-started/locally/) 2.1+, [TensorFlow](https://www.tensorflow.org/install/pip) 2.6+, and [Flax](https://flax.readthedocs.io/en/latest/) 0.4.1+.
+Transformers works with Python 3.9 - 3.12 [PyTorch](https://pytorch.org/get-started/locally/) 2.1+, [TensorFlow](https://www.tensorflow.org/install/pip) 2.6+, and [Flax](https://flax.readthedocs.io/en/latest/) 0.4.1+.


Keep it at 3.9+!

Keep it at 3.9+!

It breaks with 3.13, therefore 3.9+ is incorrect.

Rocketknight1 · 2025-05-07T13:32:49Z

README.md

-pip install transformers
+pip install "transformers[torch]"

 # uv
-uv pip install transformers
+uv pip install "transformers[torch]"


This change is good, we can keep it!

Rocketknight1 · 2025-05-07T13:33:08Z

README.md

-pip install .
+pip install .[torch]
+# optionally, you can use our script to verify python version, create venv, install from source, and verify installation.
+bash scripts/install.sh "[torch]"


We can keep .[torch] but remove the reference to install.sh!

Rocketknight1 · 2025-05-07T13:33:20Z

setup.py

+        "Programming Language :: Python :: 3.11",
+        "Programming Language :: Python :: 3.12",


These changes are good, and we could add 3.13 as well!

3.13 as well!

It breaks on Arch Linux with Python 3.13 due to transitive dependencies being pinned to 3.12.

Rocketknight1 · 2025-05-07T13:33:29Z

setup.py

        ]
    },
-    python_requires=">=3.9.0",
+    python_requires=">=3.9,<3.13",


We don't want to limit to <3.13

limit to <3.13

Have you tried it with Python 3.13? It breaks.

Aside, this is another example of a DRY violation. Why is the upper bound needed in so many places? If it isn't needed here because the version dependency is satisfied/documented elsewhere, then this can go.

Hi @DarkTyger, like I said, TF support is in maintenance mode and PyTorch is the primary framework right now! We're not going to cap the Python version for the whole library to maintain TF compatibility.

Zephyr271828 · 2025-05-07T14:33:31Z

Hi @Zephyr271828, I'm sorry for being late with this one, but I don't think we can accept this PR as-is, but we could accept some of the changes from it! I should have said something earlier, but there are a few issues:

We don't want to limit our Python version compatibility to remain compatible with Tensorflow. Right now our TF/JAX support is mostly in maintenance mode, and PyTorch is the primary framework of the library!

We don't want to add a separate install.sh script, especially since we don't need the Py<3.13 version check!

However, some of the changes here are useful, and we could keep them! I'll flag them in the comments.

Hi Matt @Rocketknight1 these suggestions totally make sense to me! I have submitted a new version of PR and would be happy if you could check if it's ready for merge:)

Rocketknight1

LGTM now!

HuggingFaceDocBuilderDev · 2025-05-08T15:05:04Z

The docs for this PR live here. All of your documentation changes will be reflected on that endpoint. The docs are available until 30 days after the last update.

…huggingface#37640) * debugging issue 36758 * debugging issue 36758 * debugging issue 36758 * updated attn_mask type specification in _flash_attention_forward * removed pdb * added a blank line * removed indentation * update constants * remove unnecessary files * created installation script, modified README * modified requirements and install.sh * undo irrelevant changes * removed blank line * fixing installation guide * modified README, python requirements, and install script * removed tests_otuput * modified README * discarded installation script and python<3.13 requirement

Zephyr271828 and others added 18 commits March 17, 2025 16:14

debugging issue 36758

b8004ac

debugging issue 36758

e00de08

debugging issue 36758

e2d659d

updated attn_mask type specification in _flash_attention_forward

aa095f5

Merge branch 'Yufeng-Xu' of github.com:Zephyr271828/transformers into…

2bf8832

… dev

removed pdb

fb45c3e

added a blank line

c53ddbb

removed indentation

f7d8fc8

Merge branch 'time-strategy' of github.com:Zephyr271828/transformers …

f609a13

…into time-strategy

update constants

ccd68db

remove unnecessary files

e4bec10

Merge branch 'main' of github.com:Zephyr271828/transformers into inst…

f4e6049

…allation

created installation script, modified README

c6ac065

modified requirements and install.sh

c6db4e7

Merge branch 'huggingface:main' into installation

bef9789

undo irrelevant changes

6be14e8

Merge branch 'installation' of github.com:Zephyr271828/transformers i…

f6797c8

…nto installation

removed blank line

a58730a

github-actions bot marked this pull request as draft April 20, 2025 18:54

Zephyr271828 changed the title ~~Installation~~ Fix incorrect installation instructions (for issue #37476) Apr 20, 2025

Zephyr271828 marked this pull request as ready for review April 20, 2025 18:55

github-actions bot requested review from ArthurZucker and Rocketknight1 April 20, 2025 18:55

DarkTyger reviewed Apr 21, 2025

View reviewed changes

fixing installation guide

7a10e7a

Rocketknight1 added the Flax label Apr 22, 2025

Zephyr271828 added 4 commits May 6, 2025 15:31

modified README, python requirements, and install script

3195f5d

merged conflicts in setup.py

baa3876

removed tests_otuput

664c5c3

modified README

e2d9e7a

Rocketknight1 reviewed May 7, 2025

View reviewed changes

discarded installation script and python<3.13 requirement

e7321e0

Rocketknight1 approved these changes May 8, 2025

View reviewed changes

Rocketknight1 merged commit 1c65aef into huggingface:main May 8, 2025
20 checks passed

vasqu mentioned this pull request May 8, 2025

[docs] add uv installation instructions for source builds #37968

Merged

		"Programming Language :: Python :: 3.11",
		"Programming Language :: Python :: 3.12",

Fix incorrect installation instructions (for issue #37476) #37640

Fix incorrect installation instructions (for issue #37476) #37640

Uh oh!

Conversation

Zephyr271828 commented Apr 20, 2025

What does this PR do?

Before submitting

Who can review?

Uh oh!

github-actions bot commented Apr 20, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Zephyr271828 Apr 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

DarkTyger Apr 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Zephyr271828 May 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Rocketknight1 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

DarkTyger May 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

DarkTyger May 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Rocketknight1 May 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Zephyr271828 commented May 7, 2025

Uh oh!

Rocketknight1 left a comment

Choose a reason for hiding this comment

Uh oh!

HuggingFaceDocBuilderDev commented May 8, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Zephyr271828 Apr 21, 2025 •

edited

Loading

DarkTyger Apr 22, 2025 •

edited

Loading

Zephyr271828 May 6, 2025 •

edited

Loading

DarkTyger May 7, 2025 •

edited

Loading

DarkTyger May 7, 2025 •

edited

Loading

Rocketknight1 May 8, 2025 •

edited

Loading