hatch python install free threading version

[abulgher]

starting from python version 3.13 there are binary versions of python executable with GIL disabled. Is there a way to specify to the hatch python install command to install specifically this version?

If not, is there a plan to add this functionality in the future?

Thanks :)

[ofek]

The variants aren't documented prominently enough, sorry about that https://hatch.pypa.io/latest/plugins/environment/virtual/#cpython

[abulgher]

Thanks @ofek, my bad that I have not checked the documentation deep enough!

If I got it right, one has to export the HATCH_PYTHON_VARIANT_GIL environmental value in the shell before launching the creation of the environment.

Is it possible to have a dedicated env defined in the pyproject.toml like this?

[tool.hatch.envs.nogil]
features = ['dev']
python = '3.13'
HATCH_PYTHON_VARIANT_GIL = 'freethreaded'

[ofek]

Yes that should work, please confirm?

[abulgher]

Not really...
Here is what I have done.

I have removed the python 3.13 because I had it already and it was the normal variant.

hatch python remove 3.13

Then I try to create the nogil environment hoping it will install automatically the proper python version/variant.

hatch env create nogil

and after a few seconds I got the message:

Environment nogil is incompatible: cannot locate Python: 3.13

If I install the 3.13 version with:

hatch python install 3.13

I get the python normal variant installed.

If I run again

hatch env create nogil

I get the environment created but with the base variant.

hatch shell nogil
python --version
Python 3.13.1
python
Python 3.13.1 (main, Dec 6 2024, 18:07:41) [MSC v.1942 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.

I'm for sure doing something wrong.

Is it possible to have two variants of the same python version installed at the same time?

[ofek]

Hmm, that might be the issue: the variant is not included in the identification at the file system level so if you already have 3.13 standard then enable the environment variable it will use that. Try hatch python remove 3.13 then in your shell set the proper environment variable then install again. That should give you the proper variant but I suspect you would no longer have access to the standard distribution. This is definitely a bug if so.

[abulgher]

So, I have tried what you suggested, but with no luck.

I have removed the installed 3.13, set the environment variable to select the freethreading variant and issued hatch python install 3.13

This is creating a folder 3.13 in the python dir, containing only a few subfolders compared to the other versions I have. The python executable is the freethreading one.

Then I try to create the nogil env. But few seconds after later, an error message appears saying that the python3.13.dll was not found. On the shell, I get this message in red:
Environment `nogil` is incompatible: cannot locate Python: 3.13
And if I try to remove the python 3.13 with hatch python remove 3.13, I get a warning message:
Distribution is not installed: 3.13

There is surely something I am doing wrong and the worst thing is that I cannot have the two variants installed at the same time. My main goal is to have two envs, one with freethreading and one without, to compare the performance of my code.

[ofek]

Can you use UV as a temporary measure?

[abulgher]

Thanks again for your help! Much appreciated!

do you mean to switch (temporary) from hatch to uv, or just to configure hatch to use uv for environment creation?

[abulgher]

Here some more testing:

• adding installer = 'uv' to the env definition is still not working.
• moving from hatch to uv is for the moment out of discussion. I need to have multiple environment matrices (development, testing, default, optional features). At the moment uv is only offering one single env as far as I understood.

Problem with 3.13t installation

If I set the environment variable HATCH_PYTHON_VARIANT_GIL = 'freethreaded' and then run hatch python install 3.13, the procedure gets to the end but the output is totally different from the other versions installed without freethreading.

This is the structure of the 3.12 python installation:

While this is the directory structure of the 3.13t

the content of the subfolder install is very similar to the one I was expecting. If I move the content of the install folder back one level, as shown here:

then the creation of the nogil environment is successful, but apparently I cannot have two pythons 3.13 with and without free threading.

It looks like that there is something wrong.

hatch --version
Hatch, version 1.14.0

[abulgher]

are there any news on this topic?

thanks for your help!