Update Dockerfiles to install packages inside a virtual environment #39098

Sai-Suraj-27 · 2025-06-28T10:02:37Z

What does this PR do?

Since we are explicitly setting this UV_PYTHON to use the global python interpreter in the containers. All packages will be installed globally.

ENV UV_PYTHON=/usr/local/bin/python

No use of creating a virtual environment as we are not using it anywhere. Right now it's just creating an extra virtual environment in the container with no packages being installed. So, uv venv can be removed.

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?

@ydshieh @Rocketknight1

ydshieh · 2025-06-28T11:21:38Z

Hi @Sai-Suraj-27 . I have some doubts regarding this. See below.

My global python is /usr/bin/python3. Using uv venv with UV_PYTHON=/usr/bin/python3 will install the package zipp to the newly created environment .venv, and yet at this point, the global python environment won't have it.

They only share the python interpreter, but all the packages are isolated.

root@fc6ee5f0b28d:~# python3 -m pip freeze
uv==0.7.16
root@fc6ee5f0b28d:~# python3 -c 'import sys; print(sys.executable)'
/usr/bin/python3
root@fc6ee5f0b28d:~# UV_PYTHON=/usr/bin/python3
root@fc6ee5f0b28d:~# echo $UV_PYTHON
/usr/bin/python3


root@fc6ee5f0b28d:~# uv venv && uv pip install zipp && uv pip freeze
Using CPython 3.10.12 interpreter at: /usr/bin/python3
Creating virtual environment at: .venv
Activate with: source .venv/bin/activate
Resolved 1 package in 31ms
Installed 1 package in 3ms
 + zipp==3.23.0
zipp==3.23.0


root@fc6ee5f0b28d:~# python3 -m pip freeze
uv==0.7.16


root@fc6ee5f0b28d:~# uv pip freeze
zipp==3.23.0


root@fc6ee5f0b28d:~#
root@fc6ee5f0b28d:~# uv run python3 -c 'import sys; print(sys.executable)'
/root/.venv/bin/python3
root@fc6ee5f0b28d:~# ls -la /root/.venv/bin/python3
lrwxrwxrwx 1 root root 6 Jun 28 11:15 /root/.venv/bin/python3 -> python

Sai-Suraj-27 · 2025-06-28T12:33:30Z

root@fc6ee5f0b28d:~# python3 -m pip freeze
uv==0.7.16
root@fc6ee5f0b28d:~# python3 -c 'import sys; print(sys.executable)'
/usr/bin/python3
root@fc6ee5f0b28d:~# UV_PYTHON=/usr/bin/python3
root@fc6ee5f0b28d:~# echo $UV_PYTHON
/usr/bin/python3


root@fc6ee5f0b28d:~# uv venv && uv pip install zipp && uv pip freeze
Using CPython 3.10.12 interpreter at: /usr/bin/python3
Creating virtual environment at: .venv
Activate with: source .venv/bin/activate
Resolved 1 package in 31ms
Installed 1 package in 3ms
 + zipp==3.23.0
zipp==3.23.0


root@fc6ee5f0b28d:~# python3 -m pip freeze
uv==0.7.16


root@fc6ee5f0b28d:~# uv pip freeze
zipp==3.23.0


root@fc6ee5f0b28d:~#
root@fc6ee5f0b28d:~# uv run python3 -c 'import sys; print(sys.executable)'
/root/.venv/bin/python3
root@fc6ee5f0b28d:~# ls -la /root/.venv/bin/python3
lrwxrwxrwx 1 root root 6 Jun 28 11:15 /root/.venv/bin/python3 -> python

Hi, @ydshieh. Thanks for immediate reply. I understand that in your code it is by default installing packages in the .venv created without activating it. But if we build the actual Dockerfiles (tf-light.dockerfile for example) & inspect the container, this is not happening.

Inside the .venv/ the site-packages directory does not contain any packages. But inside the usr/local/lib/python3.9/site-packages/ all the installed packages are present.
I am showing you the output for both commands inside the tf-light.dockerfile image container. For the command ls -la /usr/local/lib/python3.9/site-packages/ i just trimmed the output, as the actual output is very long listing all the packages installed.

root@a7ed4cb588e7:/# ls -la .venv/lib/python3.9/site-packages/
total 20
drwxr-xr-x 2 root root 4096 Jun 28 11:35 .
drwxr-xr-x 3 root root 4096 Jun 28 11:35 ..
-rw-r--r-- 1 root root   18 Jun 28 11:35 _virtualenv.pth
-rw-r--r-- 1 root root 4342 Jun 28 11:35 _virtualenv.py
root@a7ed4cb588e7:/# ls -la /usr/local/lib/python3.9/site-packages/
total 11308
drwxr-xr-x  1 root root    4096 Jun 28 11:38 .
drwxr-xr-x  1 root root    4096 Jun 10 23:51 ..
drwxr-xr-x  2 root root    4096 Jun 28 11:38 GitPython-3.1.18.dist-info
drwxr-xr-x  2 root root    4096 Jun 28 11:38 MarkupSafe-3.0.2.dist-info
drwxr-xr-x  2 root root    4096 Jun 28 11:38 PIL
drwxr-xr-x  2 root root    4096 Jun 28 11:38 PyYAML-6.0.2.dist-info
drwxr-xr-x  2 root root    4096 Jun 28 11:38 PyYAML.libs
-rw-r--r--  1 root root     119 Jun 10 23:51 README.txt
-rwxr-xr-x  1 root root  981728 Jun 28 11:37 _cffi_backend.cpython-39-x86_64-linux-gnu.so
drwxr-xr-x  2 root root    4096 Jun 28 11:35 _distutils_hack
-rw-r--r--  1 root root    6573 Jun 28 11:37 _hypothesis_ftz_detector.py
-rw-r--r--  1 root root    1214 Jun 28 11:37 _hypothesis_globals.py
-rw-r--r--  1 root root   20112 Jun 28 11:37 _hypothesis_pytestplugin.py
drwxr-xr-x  2 root root    4096 Jun 28 11:38 _multiprocess
drwxr-xr-x  8 root root    4096 Jun 28 11:38 _pytest
-rw-r--r--  1 root root    5783 Jun 28 11:37 _soundfile.py
drwxr-xr-x  2 root root    4096 Jun 28 11:38 _soundfile_data
drwxr-xr-x  2 root root    4096 Jun 28 11:38 _yaml
drwxr-xr-x  5 root root    4096 Jun 28 11:38 absl
drwxr-xr-x  3 root root    4096 Jun 28 11:38 absl_py-2.3.0.dist-info
..
..
..

Let me know, if I am missing something.

ydshieh · 2025-06-28T12:39:37Z

Thanks for sharing. Do you know why this is happening within our docker build? Maybe we are doing something wrong there.

I could take a look next week, but in case you want to dive into it.

I think it is better to figure out the way so the packages are installed inside the venv, and they are used during CI runtime

ydshieh · 2025-06-28T12:42:11Z

Thanks for sharing. Do you know why this is happening within our docker buold? Maybe we are doing something wrong there.

I could take a look next week, but in case you want to dive into it.

I think it is better to figure out the way so the packages are installed inside the venv, and they are used during CI runtime

I am also a bit surprised that we don't get problems at ci runtime even with the issue you mentioned

Sai-Suraj-27 · 2025-06-28T12:45:03Z

Thanks for sharing. Do you know why this is happening within our docker build? Maybe we are doing something wrong there.

I could take a look next week, but in case you want to dive into it.

I think it is better to figure out the way so the packages are installed inside the venv, and they are used during CI runtime

I am also not 100% sure but I think it is because we are doing this: ENV UV_PYTHON=/usr/local/bin/python . I will try to update the Dockerfiles such that packages are installed in a venv & not globally. Will get back to you. Thanks!

Sai-Suraj-27 · 2025-06-29T14:13:47Z

Hi, @ydshieh. As expected this line was causing the problem: ENV UV_PYTHON=/usr/local/bin/python. By default if we create a virtual environment using uv venv and install packages with uv pip install ... uv will install all the packages inside the created .venv instead of installing globally. But since we are setting this UV_PYTHON=/usr/local/bin/python. It is causing uv to install all packages globally.

Reference:
https://docs.astral.sh/uv/reference/environment/#uv_python
https://docs.astral.sh/uv/pip/environments/#using-arbitrary-python-environments

I built a Docker image by removing this line: ENV UV_PYTHON=/usr/local/bin/python & as expected all packages are present inside the .venv/ & not globally.

root@9433e06e57ea:/# ls -la /usr/local/lib/python3.9/site-packages/
total 60
drwxr-xr-x 1 root root 4096 Jun 29 13:07 .
drwxr-xr-x 1 root root 4096 Jun 10 23:51 ..
-rw-r--r-- 1 root root  119 Jun 10 23:51 README.txt
drwxr-xr-x 3 root root 4096 Jun 10 23:51 _distutils_hack
-rw-r--r-- 1 root root  152 Jun 10 23:51 distutils-precedence.pth
drwxr-xr-x 5 root root 4096 Jun 10 23:51 pip
drwxr-xr-x 2 root root 4096 Jun 10 23:51 pip-23.0.1.dist-info
drwxr-xr-x 5 root root 4096 Jun 10 23:51 pkg_resources
drwxr-xr-x 7 root root 4096 Jun 10 23:51 setuptools
drwxr-xr-x 2 root root 4096 Jun 10 23:51 setuptools-58.1.0.dist-info
drwxr-xr-x 3 root root 4096 Jun 29 13:07 uv
drwxr-xr-x 3 root root 4096 Jun 29 13:07 uv-0.7.16.dist-info
drwxr-xr-x 4 root root 4096 Jun 10 23:51 wheel
drwxr-xr-x 2 root root 4096 Jun 10 23:51 wheel-0.45.1.dist-info
root@9433e06e57ea:/# ls -la .venv/lib/python3.9/site-packages/
total 11328
drwxr-xr-x  1 root root   20480 Jun 29 13:10 .
drwxr-xr-x  1 root root    4096 Jun 29 13:07 ..
drwxr-xr-x  2 root root    4096 Jun 29 13:10 GitPython-3.1.18.dist-info
drwxr-xr-x  2 root root    4096 Jun 29 13:10 MarkupSafe-3.0.2.dist-info
drwxr-xr-x  2 root root    4096 Jun 29 13:10 PIL
drwxr-xr-x  2 root root    4096 Jun 29 13:10 PyYAML-6.0.2.dist-info
drwxr-xr-x  2 root root    4096 Jun 29 13:10 PyYAML.libs
-rwxr-xr-x  1 root root  981728 Jun 29 13:08 _cffi_backend.cpython-39-x86_64-linux-gnu.so
drwxr-xr-x  2 root root    4096 Jun 29 13:07 _distutils_hack
-rw-r--r--  1 root root    6573 Jun 29 13:08 _hypothesis_ftz_detector.py
-rw-r--r--  1 root root    1214 Jun 29 13:08 _hypothesis_globals.py
-rw-r--r--  1 root root   20112 Jun 29 13:08 _hypothesis_pytestplugin.py
drwxr-xr-x  2 root root    4096 Jun 29 13:10 _multiprocess
drwxr-xr-x  8 root root    4096 Jun 29 13:10 _pytest
-rw-r--r--  1 root root    5783 Jun 29 13:08 _soundfile.py
drwxr-xr-x  2 root root    4096 Jun 29 13:10 _soundfile_data
-rw-r--r--  1 root root      18 Jun 29 13:07 _virtualenv.pth
-rw-r--r--  1 root root    4342 Jun 29 13:07 _virtualenv.py
drwxr-xr-x  2 root root    4096 Jun 29 13:10 _yaml
drwxr-xr-x  5 root root    4096 Jun 29 13:10 absl
drwxr-xr-x  3 root root    4096 Jun 29 13:10 absl_py-2.3.0.dist-info
..
..

Let me know if anything needs to be changed in the CI config side.

ydshieh · 2025-06-30T13:41:48Z

Thanks for checking.

However, I think something strange here within the docker. Because I tried to some the same thing (set UV_PYTHON=/usr/local/bin/python) in a runner (not the one used by CircleCI), and yet get

#39098 (comment)

which corresponding to what mentioned in uv's documentation, i.e. only the python interpreter will be linked (i.e. share the same python interpreter, but the packages will be installed in the 2 different places.

I will have to check it in more details why there is an issue within docker (build).

Sai-Suraj-27 · 2025-06-30T14:31:34Z

Thanks for checking.

However, I think something strange here within the docker. Because I tried to some the same thing (set UV_PYTHON=/usr/local/bin/python) in a runner (not the one used by CircleCI), and yet get

#39098 (comment)

which corresponding to what mentioned in uv's documentation, i.e. only the python interpreter will be linked (i.e. share the same python interpreter, but the packages will be installed in the 2 different places.

I will have to check it in more details why there is an issue within docker (build).

Hi, @ydshieh I think the reason uv is installing in the .venv here in #39098 (comment) is because you are setting UV_PYTHON=/usr/bin/python3 which just creates a shell variable & It is not passed down to any child processes that you start from that shell. Meaning when you are next running uv pip install zipp, it will not see the UV_PYTHON variable. In contrast, if you try export UV_PYTHON=/usr/bin/python3 or UV_PYTHON=/usr/bin/python3 && uv pip install zipp then uv will not install in the .venv.

So, in Dockerfiles whe we are setting ENV UV_PYTHON=/usr/local/bin/python this is equivalent to export UV_PYTHON=/usr/local/bin/python So any command that comes after this ENV line in the Dockerfile will have access to UV_PYTHON as an exported environment variable & uv is installing packages globally due to this.

ydshieh · 2025-06-30T15:05:16Z

Very nice, I will try it to make sure, and determine what to do 🙏

ydshieh · 2025-07-08T03:21:07Z

@Sai-Suraj-27 You are completely right about export.

I built a Docker image by removing this line: ENV UV_PYTHON=/usr/local/bin/python & as expected all packages are present inside the .venv/ & not globally.

I guess I miss this comment (or misread it). That is great. I will built the (testing) images and see if they work well when using with our CircleCI workflow.

Thank you a lot for finding this, pointing out about export and find a direction to go.

ydshieh · 2025-07-08T08:02:24Z

@ArthurZucker

Do you remember why we use ENV UV_PYTHON=/usr/local/bin/python in the docker file for the CircleCI docker images?

Using it will install everything (packages) to the global python's site-packages, and .venv is empty.

As suggested by @Sai-Suraj-27 , we can either remove uv venv command (still everything is installed to global python), or remove ENV UV_PYTHON=/usr/local/bin/python (packages are install to the virtual env).

Either works for me, but maybe you can confirm we don't miss any detail why you use ENV UV_PYTHON=/usr/local/bin/python back then.

ArthurZucker · 2025-07-15T13:48:23Z

When I used ENV UV_PYTHON=/usr/local/bin/python it was because UV was just not working without this at the time!
Things have changed, uv is a lot more stable now!

ydshieh · 2025-07-15T13:52:25Z

I will try

remove ENV UV_PYTHON=/usr/local/bin/python (packages are install to the virtual env).

when I am back

…e_venv

ydshieh · 2025-08-04T08:16:27Z

I have made it to work with the .venv created by uv.

It requires a bit more change to correctly use it however, and I don't think it brings a lot of value over the current approach of using the default python.

@Sai-Suraj-27 / @ArthurZucker Could you take a look.

ydshieh · 2025-08-04T08:25:19Z

build-doc

ArthurZucker

I dont mind, the choice is up to you @ydshieh !

Removed un-necessary virtual environment creation in Dockerfiles.

e81176c

Updated Dockerfiles to install packages in a virtual environment.

c1b0f9c

Sai-Suraj-27 changed the title ~~Removed virtual environment creation in Dockerfiles~~ Update Dockerfiles to install packages inside a virtual environment Jun 29, 2025

Sai-Suraj-27 and others added 3 commits July 20, 2025 09:26

Merge branch 'main' of github.com:huggingface/transformers into remov…

c6b9470

…e_venv

Merge branch 'main' into remove_venv

b0ca58d

use venv's python

4e3ffb4

ArthurZucker reviewed Aug 11, 2025

View reviewed changes

Merge branch 'main' into remove_venv

faa4294

Update Dockerfiles to install packages inside a virtual environment #39098

Are you sure you want to change the base?

Update Dockerfiles to install packages inside a virtual environment #39098

Uh oh!

Conversation

Sai-Suraj-27 commented Jun 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this PR do?

Before submitting

Who can review?

Uh oh!

ydshieh commented Jun 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Sai-Suraj-27 commented Jun 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ydshieh commented Jun 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ydshieh commented Jun 28, 2025

Uh oh!

Sai-Suraj-27 commented Jun 28, 2025

Uh oh!

Sai-Suraj-27 commented Jun 29, 2025

Uh oh!

ydshieh commented Jun 30, 2025

Uh oh!

Sai-Suraj-27 commented Jun 30, 2025

Uh oh!

ydshieh commented Jun 30, 2025

Uh oh!

ydshieh commented Jul 8, 2025

Uh oh!

ydshieh commented Jul 8, 2025

Uh oh!

ArthurZucker commented Jul 15, 2025

Uh oh!

ydshieh commented Jul 15, 2025

Uh oh!

ydshieh commented Aug 4, 2025

Uh oh!

ydshieh commented Aug 4, 2025

Uh oh!

ArthurZucker left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Sai-Suraj-27 commented Jun 28, 2025 •

edited

Loading

ydshieh commented Jun 28, 2025 •

edited

Loading

Sai-Suraj-27 commented Jun 28, 2025 •

edited

Loading

ydshieh commented Jun 28, 2025 •

edited

Loading