DEV Community: Edgar Montano

Python 3.14 Free-Threading True Parallelism Without the GIL

Edgar Montano — Fri, 07 Nov 2025 19:19:10 +0000

Python's Global Interpreter Lock (GIL) has constrained multi-core CPU utilization for decades. Python 3.14 changes this with official support for free-threaded builds and the concurrent.interpreters module, enabling true CPU parallelism with up to 4x performance improvements for CPU-bound tasks.

This is a condensed version of my comprehensive guide. For complete code examples, production patterns, and migration strategies, check out the full article on my blog.

Quick Installation

Using UV (Fastest Method)

# Install free-threaded Python 3.14
$ uv python install 3.14t

# Verify installation
$ uv run --python 3.14t python -VV
Python 3.14.0 free-threading build (main, Oct 7 2025, 15:35:12)

Performance Impact: Real Numbers

I ran benchmarks comparing standard Python 3.14 with the free-threaded build on CPU-intensive tasks:

import threading
import time
import hashlib

def cpu_intensive_task(iterations=1_000_000):
    """Compute SHA256 hashes to simulate CPU-bound work"""
    data = b"Python 3.14 benchmark"
    for _ in range(iterations):
        hashlib.sha256(data).hexdigest()

def run_benchmark(num_threads=4):
    threads = []
    start_time = time.perf_counter()

    for _ in range(num_threads):
        thread = threading.Thread(target=cpu_intensive_task)
        thread.start()
        threads.append(thread)

    for thread in threads:
        thread.join()

    return time.perf_counter() - start_time

Results on 8-core System

Threads	Standard Python	Free-threaded Python	Speedup
1	1.52s	1.61s	0.94x
2	3.01s	1.58s	1.90x
4	5.98s	1.55s	3.86x
8	11.84s	1.59s	7.45x

Free-threaded Python maintains consistent execution time regardless of thread count, achieving near-linear scaling.

Multiple Interpreters: New Concurrency Model

Python 3.14 introduces concurrent.interpreters, exposing functionality that existed in the C-API for 20 years:

from concurrent.futures import InterpreterPoolExecutor

def process_data(chunk):
    # Each interpreter has isolated state
    import numpy as np
    return np.mean(chunk)

# Process in parallel using multiple interpreters
with InterpreterPoolExecutor(max_workers=4) as executor:
    chunks = [list(range(i*1000, (i+1)*1000)) for i in range(10)]
    results = list(executor.map(process_data, chunks))

Each interpreter has:

Separate GIL (or no GIL in free-threaded builds)
Isolated module imports
Independent runtime state
Minimal sharing overhead

Real-World Application

Here's a practical example processing CSV data in parallel:

from concurrent.futures import InterpreterPoolExecutor
import csv
import hashlib

def process_csv_chunk(chunk_data):
    """Process chunk in isolated interpreter"""
    results = []
    for row in chunk_data:
        # CPU-intensive processing
        row_str = '|'.join(str(v) for v in row.values())
        hash_val = hashlib.sha256(row_str.encode()).hexdigest()
        results.append(hash_val[:8])
    return results

# Split CSV into chunks and process in parallel
with InterpreterPoolExecutor(max_workers=4) as executor:
    results = list(executor.map(process_csv_chunk, chunks))

Key Considerations

Extension Compatibility

Not all C extensions support free-threading yet. Check compatibility:

import sys
import importlib

def check_gil_compatibility(module_name):
    original = sys._is_gil_enabled()
    module = importlib.import_module(module_name)
    if original != sys._is_gil_enabled():
        print(f"Warning: {module_name} re-enabled the GIL")
        return False
    return True

Thread Safety

Built-in types use internal locks, but explicit synchronization is recommended:

import threading

class ThreadSafeCache:
    def __init__(self):
        self._cache = {}
        self._lock = threading.RLock()

    def get(self, key):
        with self._lock:
            return self._cache.get(key)

    def set(self, key, value):
        with self._lock:
            self._cache[key] = value

Current Limitations

Single-threaded overhead: 5-10% penalty in free-threaded mode
Extension support: Many packages need updates for full compatibility
Interpreter startup: ~10-50ms per interpreter creation
Limited sharing: Only basic types shareable between interpreters (for now...)

What This Means for Python

Python 3.14's free-threading support represents Phase II of PEP 703's implementation. The free-threaded build is officially supported but optional. Phase III will make it the default, finally removing the GIL constraint that has defined Python's concurrency for decades.

For CPU-bound workloads, the performance improvements are substantial. Data science, machine learning, and high-throughput web applications can now achieve true multi-core parallelism without multiprocessing overhead.

Want to Learn More?

This article covers the essentials, but there's much more to explore:

Complete benchmarking suite with detailed metrics
Production deployment patterns and monitoring
Advanced inter-interpreter communication
Compatibility matrices for popular packages
Migration case studies from real applications

Read the complete guide on my blog →

Resources

What are your thoughts on Python's new parallelism capabilities? Have you tested free-threaded Python with your workloads? Share your experiences in the comments!

Follow me for more Python performance and optimization content:

Blog: edgarmontano.com
GitHub: @edgarmontano

How to setup .env in Python

Edgar Montano — Fri, 20 Jan 2023 20:01:52 +0000

What is a .env file?

A .env is a simple file that you can create that can store and host environment variables. Environment variables offer a way for your application to store and access variables relating to the environment of your application.

This could be anything from API keys to login credentials and passwords or special flags that you pass to your application to indicate production or development builds. .env files should never be committed to your project and should remain local only. As long as your system is not compromised, your API keys will not be compromised either.

Why use a .env file?

.env are used to store sensitive environment variables locally.

This means you can store variables pertaining to the environment, such as production or development variables needed across your application. These types of variables include API keys and login credentials for database connections and other application sensitive information.

How to setup a .env file

1.To start using a .env simply create a file called .env in the root of your project.

2.Add the .env file to your .gitignore file. If you do not have a .gitignore you can download a default Python .gitignore.

.gitignore should be located in the root of your project (same place as .env).

The purpose of a .gitignore file is to prevent git from committing specific files that are listed in this file, hence the name .gitignore since it ignores any file or directory listed in this file.

3.Set your environment variables, API keys, and any sensitive information such as login credentials inside the .env file using the following format:

DISCORD_API_TOKEN=<API_KEY>
DISCORD_USERNAME=<USERNAME>
DISCORD_PASSWORD=<PASSWORD>

Note the < and > delimiter just means you replace the contents of that with the actual API_KEY you desire to hide. An example of a .env file is listed below:

DISCORD_API_TOKEN=1234-1234-1234-1234
DISCORD_USERNAME=TotallyFakeUserName
DISCORD_PASSWORD=Passw0rd!

4.Before accessing the environment variable in our application we need to install a package that lets us locate and load the .env file.

For this, we'll use Python's package installer to retrieve the package python-dotenv for us, which will allow us to load our .env and access our variables within our application.

Simply install python-dotenv by using the following command in the terminal:

pip install python-dotenv

If this command does not work, you can try alternatively using python -m pip install python-dotenv to install the package.

5.Now that we have the correct package installed we can load the .env file into our application.

Normally we would have to hardcode the location of our .env file, but luckily there is a package to automatically locate the .env file included in python-dotenv, this function is called find_dotenv() which attempts to find our .env within our project.

from dotenv import load_dotenv, find_dotenv

# find the .env file and load it 
load_dotenv(find_dotenv())

6.At this point, we have our .env file loaded in memory, but we have no way of accessing the variables just yet.

Python has a built-in method for this. We'll be using the os package which is already included in Python. The os package offers us a function called getenv() which will allow us to get our environment variables.

from os import getenv
from dotenv import load_dotenv, find_dotenv

# find the .env file and load it 
load_dotenv(find_dotenv()
# access environment variable 
token = getenv("DISCORD_BOT_TOKEN")

What if you are creating an open source application that needs a .env file?

If you intend on making your project public but don't want to expose your API keys .env is still the solution.

A good practice is creating a .env.example file that you commit to your code base. This file should only be a template of the environment variables the user is required to input and should not actually contain any keys or sensitive data. So for our example, we would create a .env.example file with the following contents:

DISCORD_BOT_TOKEN=<API_KEY>
DISCORD_USERNAME=<USERNAME>
DISCORD_PASSWORD=<PASSWORD>

This can be safely committed to our project without exposing any sensitive information.

In your applications README you can indicate that a user needs to correctly set this file up and they can use the following command to create their own .env file from this template:

cp .env.example .env

This command simply copies the example .env file and creates an actual .env file, here the user can modify the .env file and add their credentials, API keys, etc without exposing it to the world since the .gitignore is set to ignore the .env file.

.env Naming Conventions

1..env should have variables capitalized. This allows for better code readability, this convention is common when it comes to naming constant variables. An example is:

Incorrect:

discord_bot_token=1234-1234-1234

Correct:

DISCORD_BOT_TOKEN=1234-1234-1234

2..env should be as explicit as possible when it comes to its variables. For instance, the variable TOKEN= can indicate any type of token, however, if we name the variable DISCORD_API_TOKEN= it becomes clear what exactly we are describing.

3..env does not need quotes for variables unless the variable contains special characters or spaces. An example of this is as follows:

DISCORD_BOT_TOKEN=1234-1345-5345-3453

However, the following below needs quotations surrounding the variable since it has special characters towards the end or it has a space.

DISCORD_BOT_TOKEN="c2RmZ2FmZ2FnYWRmZ2FkZ2RmZ2FkZg=="
USERNAME="Bob Doll"

If we do not surround the items in quotes for these instances, the DISCORD_BOT_TOKEN string has double == sign towards the end, which may confuse parsers for your .env similarly, spaces between items will get ignored and only the first characters will be printed, so if we do not include the quotes for the USERNAME variable, we will only get back the value Bob when trying to access the username instead of the full name Bob Doll.

Full discord bot code example

👍 If you found this article helpful please drop a like on this.
❔If you have any other questions please comment below.

Source:
Stop hardcoding API keys: how to secure your code from attackers