Python: Cannot pickle local object in multiprocessing

Quick fix

Read the commands before running them. Anything that restarts a service, deletes data or changes permissions should be tried on a non-production system first.

Quick fix

# Define function at module level
def worker(x):
    return x * 2

if __name__ == '__main__':
    from multiprocessing import Pool
    with Pool() as p:
        results = p.map(worker, data)
# Or use dill
import dill

How to diagnose Python errors

Python errors cluster around the import system (which is really about sys.path and the active interpreter), environment management (which interpreter and which site-packages), and concurrency (the GIL, event loops, and pickling constraints in multiprocessing). A very large share of "module not found" reports are simply the wrong interpreter, which is why the first command should always identify it.

If the quick fix above does not resolve it, work through these steps. They apply to this whole class of error, not just to this one message, which is usually what saves the time.

Identify the interpreter and its paths: python -c "import sys; print(sys.executable); print(sys.path)". This resolves most import errors immediately.
Install into the interpreter you are running, not the one on PATH: python -m pip install … rather than bare pip.
Read tracebacks bottom-up. The last line is the exception; the frames above show the call chain, and the relevant frame is usually your code, not the library's.
For encoding errors, name the encoding explicitly and decide on an error policy, such as open(path, encoding='utf-8', errors='replace'), rather than relying on the locale default.
For multiprocessing pickling errors, move the target function to module level. Closures, lambdas and locally defined classes cannot be pickled.

Tools worth reaching for

python -m pip
python -c 'import sys; print(sys.path)'
pip check
py-spy dump
uv / pipx for isolation

Authoritative references

Primary documentation for this error, worth reading before applying any fix in production.

docs.python.org

Related Python errors

See all 35 Python errors →

Browse other categories

Something missing or wrong?

This entry is maintained by hand. If the fix is out of date, incomplete, or you have a better one, email a correction and it will be reviewed.