Add sys._is_gil_enabled()

Feature or enhancement

I propose adding a new function to the sys module to check if the GIL is current enabled:

sys._is_gil_enabled() -> bool

Return True if the GIL is currently enabled and False if the GIL is currently disabled.

The function would always return True in builds that do not support free-threading. In the free-threaded build, the the GIL might be dynamically enabled or disabled depending on imported modules.

EDIT: Changed name to use underscore prefix

Linked PRs

gh-117514: Add sys._is_gil_enabled() function #118514

What do you expect developers to do with this value? Is it merely for reporting details about bugs? Or is there some programmatic reason you may want to know this?

I'd expect likely just reporting. Similar to things like sys.is_stack_trampoline_active(). It isn't an API likely to be logically useful to most code. But the reporting aspect is important, especially for test runners.

I think the diagnostic and bug reporting uses are most straight-forward: is the GIL really disabled? Especially because it looks like we will be temporarily enabling the GIL around imports.

I think it might also be useful in a few cases for choosing reasonable defaults: i.e., does a thread-pool or multiprocessing backend make more sense as a default in some library (like PyTorch data loaders or joblib).

I fear it won't be particularly useful for either of those cases with the current proposed (temporary?) semantics.

Reporting feels like it ought to be "was the GIL enabled when X went wrong", while selecting defaults feels like "will the GIL be enabled under normal operation".

Otherwise the semantics of "don't call this during import" are going to be very unhelpful, both to explain and to reveal internal behaviour details and require users to design around them.

How about a CPython-specific sys._is_gil_enabled() to return the status right now, and a more generic sys.is_free_threaded() (that could also be implemented in other runtimes) to return the intent of the runtime?

(FWIW, I'd have argued is_stack_trampoline_active() should have an underscore, like sys._getframe() and sys._git, but I missed that proposal.)

That seems like a more confusing API to me. I don't think there's a sufficient need for sys.is_free_threaded() and "intent of the runtime" strikes me as too vague of a concept to be useful. We already have other mechanisms for querying the build configuration and runtime initialization flags.

What do you mean by "don't call this during import"?

We are only planning to do the temporary GIL enabling around imports of C-API extensions, not Python modules so I don't think there's any reason not to call sys.is_gil_enabled() during an import. I don't think users have to design around it.

We already have other mechanisms for querying the build configuration and runtime initialization flags.

Mechanisms that don't exist in, say, IronPython, which is nonetheless free threaded, and given the choice between threads or processes you would likely choose threads for similar kinds of tasks that you would under free-threaded CPython.

The sys module is supposed to be consistent across implementations, so it's worth considering how other implementations will explain and handle the function.

The sys module is supposed to be consistent across implementations, so it's worth considering how other implementations will explain and handle the function.

I agree, and I think that sys.is_gil_enabled() is straight-forward to use and explain: if implemented in IronPython it can always return False. If implemented in PyPy, it can always return True.

It just feels a bit weird to suddenly introduce "GIL" as a Python-wide concept when previously it was only ever a CPython implementation detail (a public one, to be sure, but not a cross-implementation concern in any way). Especially since the plan is to eventually have everyone return False all the time.

Why is it so bad to make it a documented underscored function _is_gil_enabled? (And thereby not require other implementations to worry about it.)

I prefer sys.is_gil_enabled, but I don't think having only the underscored sys._is_gil_enabled() is so bad.

It's more the combination of sys._is_gil_enabled() and sys.is_free_threaded that I think is confusing.

It's also fair to just start with the _is_gil_enabled() name so that we can change this later. (feel free to document that _ API, just mention that its existence or name may change in future minor python versions so people who want to use it should check for it). We can base a future decision to make a non _ name based on what we find users actually found a need for.

I've updated the issue to sys._is_gil_enabled().

I came here to ask for this feature, I needed it to determine which execution model would work best (multiprocessing or thread pools) at runtime and the python -m sysconfig output only told me the compile-time value.

In answer to the "why would anyone need this", I'd just spent an hour looking for this flag :-)

In answer to the "why would anyone need this", I'd just spent an hour looking for this flag :-)

I was aware of this scenario, which is why I suggested is_free_threaded as a generic alternative to answer "should I use subprocesses or threads" without necessarily exposing implementation details.

pythongh-117514: Add `sys._is_gil_enabled()` function

gh-117514: Add `sys._is_gil_enabled()` function (#118514)

pythongh-117514: Add `sys._is_gil_enabled()` function (python#118514)

Is there a C API stable way of checking this?

There's no dedicated C API function. You can call Python functions from C. Something like:

int
is_gil_enabled(void)
{
    PyObject *sys_mod = NULL;
    PyObject *func = NULL;
    PyObject *res = NULL;
    int ret = -1;

    sys_mod = PyImport_ImportModule("sys");
    if (sys_mod == NULL) {
        return -1;
    }

    func = PyObject_GetAttrString(sys_mod, "_is_gil_enabled");
    if (func == NULL) {
        if (PyErr_ExceptionMatches(PyExc_AttributeError)) {
            PyErr_Clear();
            ret = 1;
        }
        goto done;
    }

    if (!PyCallable_Check(func)) {
        ret = 1;
        goto done;
    }

    res = PyObject_CallNoArgs(func);
    if (res == NULL) {
        ret = -1;
        goto done;
    }

    ret = PyObject_IsTrue(res);

done:
    Py_XDECREF(res);
    Py_XDECREF(func);
    Py_DECREF(sys_mod);
    return ret;
}

Thanks for the confirmation, this is what I was able to determine as well; filed #143747 as a feature request.

Navigation Menu

Repository navigation

Add `sys._is_gil_enabled()` #117514

Feature or enhancement

Linked PRs

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Add sys._is_gil_enabled() #117514

Description

Feature or enhancement

Linked PRs

Activity

zooba commented on Apr 3, 2024

gpshead commented on Apr 3, 2024

colesbury commented on Apr 3, 2024

zooba commented on Apr 3, 2024

colesbury commented on Apr 3, 2024

colesbury commented on Apr 3, 2024

zooba commented on Apr 3, 2024

colesbury commented on Apr 3, 2024

zooba commented on Apr 3, 2024

colesbury commented on Apr 3, 2024

gpshead commented on Apr 3, 2024

colesbury commented on Apr 3, 2024

tonybaloney commented on Apr 23, 2024

zooba commented on Apr 24, 2024

devinrsmith commented on Jan 12, 2026

colesbury commented on Jan 12, 2026

devinrsmith commented on Jan 12, 2026

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions

Add `sys._is_gil_enabled()` #117514