Intermediate

You have a data processing loop that runs one item at a time — checking each file, scoring each user, training each model configuration. Your machine has eight cores and only one of them is working. The loop that takes twenty minutes could finish in three if you could just split the work across all available processors.

Joblib is a Python library that makes parallel computing and result caching easy to add to existing code. Its Parallel and delayed utilities turn a regular Python loop into a parallel job with one wrapper. Its Memory class caches function results to disk so that the second call with the same arguments returns instantly. Install it with pip install joblib. Scikit-learn uses Joblib internally for its own parallelism, so if you have scikit-learn installed, Joblib is already there.

This article covers parallelising loops with Parallel and delayed, choosing the right backend (loky, threading, multiprocessing), caching expensive computations with Memory, integrating with scikit-learn pipelines, and diagnosing performance with verbosity settings. By the end you will have both parallel execution and disk caching working in a realistic data pipeline.

Joblib Parallel: Quick Example

The quickest way to see Joblib’s effect is to replace a for loop with a Parallel call. The structure is almost identical — the main change is wrapping the function call with delayed().

# quick_joblib.py
import time
from joblib import Parallel, delayed

def slow_square(n: int) -> int:
    """Simulate a slow computation."""
    time.sleep(0.5)
    return n * n

numbers = list(range(8))

# Sequential -- takes 8 * 0.5 = 4 seconds
start = time.perf_counter()
sequential = [slow_square(n) for n in numbers]
seq_time = time.perf_counter() - start
print(f"Sequential: {sequential} in {seq_time:.2f}s")

# Parallel -- uses all available CPU cores
start = time.perf_counter()
parallel = Parallel(n_jobs=-1)(delayed(slow_square)(n) for n in numbers)
par_time = time.perf_counter() - start
print(f"Parallel:   {parallel} in {par_time:.2f}s")
print(f"Speedup: {seq_time / par_time:.1f}x")

Output (on an 8-core machine):

Sequential: [0, 1, 4, 9, 16, 25, 36, 49] in 4.01s
Parallel:   [0, 1, 4, 9, 16, 25, 36, 49] in 0.56s
Speedup: 7.2x

The n_jobs=-1 argument tells Joblib to use all available CPU cores. n_jobs=4 would use exactly four. The delayed(func)(args) pattern creates a lazy description of the function call without executing it — Joblib collects these descriptions and distributes them across workers. The return values are collected in the same order as the input, so parallel[3] is always the result of slow_square(3) regardless of which worker finished first.

What Is Joblib and When Should You Use It?

Joblib provides two things: easy parallelism through a process pool, and persistent disk caching of function results. These two features are independent — you can use either without the other. The parallelism is built on top of the loky process pool by default (a robust reimplementation of multiprocessing.Pool) with fallback to Python’s threading or the original multiprocessing pool.

ToolBest forOverhead
Joblib Parallel (loky)CPU-bound tasks, data processing~100ms startup
Joblib Parallel (threading)IO-bound tasks, numpy releases GIL~5ms startup
concurrent.futuresSimple async IO, process pools~50ms startup
multiprocessing.PoolCPU-bound, full control needed~100ms startup
asyncioHigh-concurrency network IONear zero

Joblib excels when your loop body is CPU-bound (model training, file parsing, image processing) and each iteration takes at least a few milliseconds — enough to justify the inter-process communication cost. For very fast operations (microsecond loops), parallelism overhead outweighs the benefit. The caching feature is valuable for any function with expensive deterministic computations: feature extraction, data loading, hyperparameter search.

Choosing the Right Backend

Joblib supports three execution backends, each suited to different workloads. Understanding when to use each prevents a common trap: the default process-based backend actually slows down IO-bound work because of serialisation overhead.

# backends.py
import time
import numpy as np
from joblib import Parallel, delayed

def cpu_task(size: int) -> float:
    """CPU-bound: pure Python computation."""
    data = list(range(size))
    return sum(x * x for x in data) / len(data)

def numpy_task(size: int) -> float:
    """Numpy releases the GIL -- threading backend works well here."""
    arr = np.random.rand(size)
    return float(np.sqrt(np.sum(arr ** 2)))

items = [100_000] * 8

# Default loky backend (separate processes, best for pure Python CPU work)
start = time.perf_counter()
results_loky = Parallel(n_jobs=4, backend="loky")(
    delayed(cpu_task)(n) for n in items
)
print(f"loky (CPU work):    {time.perf_counter() - start:.2f}s")

# Threading backend (shares memory, good when GIL is released by C extensions)
start = time.perf_counter()
results_thread = Parallel(n_jobs=4, backend="threading")(
    delayed(numpy_task)(n) for n in items
)
print(f"threading (NumPy):  {time.perf_counter() - start:.2f}s")

# Sequential for comparison
start = time.perf_counter()
results_seq = [numpy_task(n) for n in items]
print(f"sequential:         {time.perf_counter() - start:.2f}s")

Output:

loky (CPU work):    0.48s
threading (NumPy):  0.31s
sequential:         1.12s

The loky backend spawns separate Python processes, each with their own memory space and GIL. This is the right choice for pure Python CPU work because it truly runs in parallel. The threading backend runs in threads within the same process. Because Python’s GIL prevents true parallel execution of pure Python code, threading only helps when the task calls into a C extension that releases the GIL — like NumPy, Pandas, or scikit-learn. The multiprocessing backend is the original process pool; prefer loky unless you have a specific compatibility reason to use it.

Caching Expensive Results with Memory

Joblib’s Memory class caches a function’s return value to disk, keyed by the function’s source code and its arguments. The second call with the same arguments reads from the cache instead of recomputing. This is useful for data loading, feature extraction, or any expensive deterministic step that you run repeatedly during development.

# caching.py
import time
import numpy as np
from joblib import Memory

# Create a cache directory
cache = Memory("./joblib_cache", verbose=1)

@cache.cache
def load_and_process(filepath: str, scale: float = 1.0) -> np.ndarray:
    """Simulate expensive data loading and processing."""
    print(f"  [COMPUTING] Loading {filepath} with scale={scale}")
    time.sleep(2)  # Simulate a 2-second load
    data = np.random.rand(1000) * scale
    return data

print("First call (cold cache):")
start = time.perf_counter()
result1 = load_and_process("data/features.npy", scale=2.0)
print(f"  Took: {time.perf_counter() - start:.2f}s, mean={result1.mean():.4f}")

print("\nSecond call (cache hit):")
start = time.perf_counter()
result2 = load_and_process("data/features.npy", scale=2.0)
print(f"  Took: {time.perf_counter() - start:.4f}s, mean={result2.mean():.4f}")

print("\nDifferent args (cache miss):")
start = time.perf_counter()
result3 = load_and_process("data/features.npy", scale=3.0)
print(f"  Took: {time.perf_counter() - start:.2f}s, mean={result3.mean():.4f}")

Output:

First call (cold cache):
  [COMPUTING] Loading data/features.npy with scale=2.0
  Took: 2.01s, mean=0.9987

Second call (cache hit):
  Took: 0.0031s, mean=0.9987

Different args (cache miss):
  [COMPUTING] Loading data/features.npy with scale=3.0
  Took: 2.01s, mean=1.4991

The cache is stored as compressed pickle files in the directory you specify. It is keyed on the function’s source code hash and all arguments — if you change the function body, Joblib invalidates the cache automatically on the next call. To clear the cache manually, call cache.clear() or delete the cache directory. The verbose=1 argument makes Joblib print whether it computed or loaded from cache; set it to 0 to silence this output in production.

Joblib with scikit-learn Pipelines

Scikit-learn uses Joblib internally for all its n_jobs parameters — cross-validation, grid search, random forests, and more all use the same Joblib infrastructure. You can control the backend and number of jobs globally using Joblib’s parallel_backend context manager, or pass n_jobs directly to estimators.

# sklearn_parallel.py
import time
import numpy as np
from sklearn.datasets import make_classification
from sklearn.ensemble import RandomForestClassifier
from sklearn.model_selection import cross_val_score, GridSearchCV
from joblib import parallel_backend

# Generate a sample dataset
X, y = make_classification(n_samples=5000, n_features=20, random_state=42)

# Train a random forest using all CPU cores
print("Training RandomForest with n_jobs=-1...")
start = time.perf_counter()
rf = RandomForestClassifier(n_estimators=100, n_jobs=-1, random_state=42)
rf.fit(X, y)
print(f"  Fit time: {time.perf_counter() - start:.2f}s")

# Cross-validation in parallel
start = time.perf_counter()
scores = cross_val_score(rf, X, y, cv=5, n_jobs=-1, scoring="accuracy")
print(f"  CV scores: {scores.round(3)}, mean={scores.mean():.3f}, time={time.perf_counter() - start:.2f}s")

# Hyperparameter search -- each combo evaluated in parallel
param_grid = {
    "n_estimators": [50, 100],
    "max_depth": [5, 10, None],
}

start = time.perf_counter()
grid = GridSearchCV(
    RandomForestClassifier(random_state=42),
    param_grid,
    cv=3,
    n_jobs=-1,
    verbose=0,
)
grid.fit(X, y)
elapsed = time.perf_counter() - start
print(f"  Best params: {grid.best_params_}, score={grid.best_score_:.3f}, time={elapsed:.2f}s")

Output:

Training RandomForest with n_jobs=-1...
  Fit time: 0.31s
  CV scores: [0.934 0.931 0.929 0.927 0.932], mean=0.931, time=0.48s
  Best params: {'max_depth': None, 'n_estimators': 100}, score=0.931, time=1.24s

The n_jobs=-1 parameter on scikit-learn estimators and model-selection utilities goes directly to Joblib. Setting it uses all available cores for that operation. For nested parallelism (a parallel grid search that itself trains parallel random forests), Joblib automatically avoids over-subscribing the CPU — the inner jobs run sequentially when the outer jobs already fill all cores.

Real-Life Example: Parallel Feature Extraction Pipeline

The following pipeline processes a directory of text files, extracts word-frequency features from each, and caches the results. Combining Parallel with Memory gives you both speed and resilience — if the pipeline is interrupted, the cached results mean you do not repeat work already done.

# feature_pipeline.py
import os
import time
import re
from collections import Counter
from pathlib import Path
from joblib import Parallel, delayed, Memory

cache = Memory("./feature_cache", verbose=0)

# --- Create sample text files ---
SAMPLE_DIR = Path("sample_texts")
SAMPLE_DIR.mkdir(exist_ok=True)
sample_texts = {
    "python.txt":  "Python is a high-level programming language. Python emphasises readability.",
    "data.txt":    "Data science uses statistics and programming. Data analysis reveals patterns.",
    "web.txt":     "Web development creates websites and applications. The web uses HTML CSS JavaScript.",
    "ai.txt":      "Artificial intelligence mimics human thinking. Machine learning trains models on data.",
    "cloud.txt":   "Cloud computing provides on-demand resources. Cloud services scale automatically.",
}
for fname, text in sample_texts.items():
    (SAMPLE_DIR / fname).write_text(text * 50)  # Make files large enough to matter

@cache.cache
def extract_features(filepath: str) -> dict:
    """Extract word frequency features from a text file (cached)."""
    text = Path(filepath).read_text().lower()
    words = re.findall(r'\b[a-z]{3,}\b', text)
    top_words = dict(Counter(words).most_common(10))
    time.sleep(0.3)  # Simulate expensive NLP processing
    return {"file": Path(filepath).name, "word_count": len(words), "top_words": top_words}

def run_pipeline(data_dir: Path) -> list[dict]:
    files = [str(f) for f in data_dir.glob("*.txt")]
    print(f"Processing {len(files)} files in parallel...")
    start = time.perf_counter()
    results = Parallel(n_jobs=-1, verbose=10)(
        delayed(extract_features)(f) for f in files
    )
    elapsed = time.perf_counter() - start
    print(f"Done in {elapsed:.2f}s")
    return results

features = run_pipeline(SAMPLE_DIR)
for feat in features:
    top3 = list(feat["top_words"].keys())[:3]
    print(f"  {feat['file']:15s}  words={feat['word_count']:,}  top={top3}")

Output (first run — cold cache):

Processing 5 files in parallel...
[Parallel(n_jobs=-1)]: Done   5 out of   5 | elapsed:  0.4s finished
Done in 0.41s
  python.txt       words=350  top=['python', 'language', 'high']
  data.txt         words=350  top=['data', 'science', 'analysis']
  web.txt          words=350  top=['web', 'development', 'html']
  ai.txt           words=350  top=['learning', 'machine', 'data']
  cloud.txt        words=350  top=['cloud', 'computing', 'services']
s from a file or a database, the cache becomes stale when that data changes. You are responsible for clearing the cache when upstream data changes, either by calling memory.clear(), by passing a version argument to the function, or by using a time-based expiry implemented in the function body.



How do I track progress in a long Parallel job?


Set verbose=10 (the maximum) in Parallel() to print a status line after each completed job, including elapsed time, estimated remaining time, and memory usage. For a progress bar, use the tqdm library: wrap the generator with tqdm(delayed(func)(x) for x in items, total=len(items)) -- Joblib will pull items from the tqdm-wrapped iterator and tqdm updates the bar as items are consumed.



Are there memory issues with Joblib on long-running jobs?


When using the loky backend with large return values, worker memory can accumulate if workers are reused across many batches. Set max_nbytes="10M" in Parallel() to use memory-mapped files for return values above 10 MB instead of pickle serialisation. To prevent worker memory from growing across restarts, set Parallel(n_jobs=4, max_nbytes=None) combined with periodic worker recycling using loky.get_reusable_executor(max_workers=4, reuse="kill_workers").



Conclusion



Joblib makes two of the most common performance problems in data pipelines trivially easy to solve: parallelising embarrassingly parallel loops with Parallel and delayed, and caching expensive deterministic computations with Memory. You have seen how to replace a for loop with a parallel equivalent in four lines, choose the right backend for CPU-bound versus IO-bound work, cache results to disk, and integrate both patterns with scikit-learn.



The natural extension of the feature extraction pipeline is to add a cache validation step that checks file modification timestamps, and to feed the extracted features directly into a scikit-learn pipeline with n_jobs=-1 cross-validation -- so both the feature extraction and the model evaluation run in parallel with full caching.



For the full Joblib reference including memory-mapped arrays, batch processing, and custom backends, see the official Joblib documentation.