deepfakes/faceswap · critical · FaceswapError

Faceswap ran out of RAM running convert. Conversion is very

Error message

Faceswap ran out of RAM running convert. Conversion is very system RAM heavy, so this can happen in certain circumstances when you have a lot of CPUs but not enough RAM to support them all.\nYou should lower the number of processes in use by either setting the 'singleprocess' flag (-sp) or lowering the number of parallel jobs (-j).

What it means

FaceswapError raised in Convert.process when the run dies with MemoryError: convert spawns multiple patch/spawn processes each holding model copies and image buffers, so many-CPU/low-RAM machines exhaust system RAM. The original MemoryError is chained (raise ... from err). The message prescribes lowering process count via -sp (singleprocess) or -j.

Source

Thrown at scripts/convert.py:248

        """
        logger.debug("Starting Conversion")
        # queue_manager.debug_monitor(5)
        try:
            self._convert_images()
            self._disk_io.save_thread.join()
            queue_manager.terminate_queues()

            finalize(self._images.count,
                     self._predictor.faces_count,
                     self._predictor.verify_output)
            logger.debug("Completed Conversion")
        except MemoryError as err:
            msg = ("Faceswap ran out of RAM running convert. Conversion is very system RAM "
                   "heavy, so this can happen in certain circumstances when you have a lot of "
                   "CPUs but not enough RAM to support them all."
                   "\nYou should lower the number of processes in use by either setting the "
                   "'singleprocess' flag (-sp) or lowering the number of parallel jobs (-j).")
            raise FaceswapError(msg) from err

    def _convert_images(self) -> None:
        """Start the multi-threaded patching process, monitor all threads for errors and join on
        completion."""
        logger.debug("Converting images")
        self._patch_threads.start()
        while True:
            self._check_thread_error()
            if self._disk_io.completion_event.is_set():
                logger.debug("DiskIO completion event set. Joining Pool")
                break
            if self._patch_threads.completed():
                logger.debug("All patch threads completed")
                break
            sleep(1)
        self._patch_threads.join()

        logger.debug("Putting EOF")

View on GitHub (pinned to f530cb7508)

Solutions

Lower parallelism: re-run convert with -j 2 (or 1)
Or set -sp/--singleprocess to run everything in one process
Free memory first: close other applications, add swap as a stopgap, or convert smaller images

Example fix

# before
python faceswap.py convert -i in -o out -m /models/m -j 16

# after
python faceswap.py convert -i in -o out -m /models/m -j 2
# or single process:
python faceswap.py convert -i in -o out -m /models/m -sp

Defensive patterns

Strategy: fallback

Validate before calling

# before launching convert, sanity-check RAM vs job count (rule of thumb)
import os
free_gb = os.sysconf('SC_PAGE_SIZE') * os.sysconf('SC_AVPHYS_PAGES') / 2**30
if args.jobs and args.jobs > 1 and free_gb < 2.0 * args.jobs:
    print(f"WARNING: ~{free_gb:.1f}GB free for {args.jobs} jobs; consider -j 1 or -sp")

Try / catch

from lib.exceptions import FaceswapError
try:
    convert.process()
except FaceswapError as err:
    if "out of RAM" in str(err):
        rerun_convert(singleprocess=True)  # fallback with -sp
    else:
        raise

Prevention

Start convert with conservative -j (1-2) and increase only if RAM headroom allows
Monitor free RAM during the first minutes of convert; kill early instead of waiting for OOM
Close other large processes (browsers, other ML jobs) before converting

When it happens

Trigger: Convert with high -j (parallel jobs) on a machine with many cores but insufficient RAM for that many model-loaded processes; large input images or a big model amplify per-process footprint. Python raises MemoryError inside the convert loop and it is re-wrapped.

Common situations: Default -j set to CPU count on a 32+ core workstation with modest RAM, converting 4K frames, or running convert alongside other memory-heavy jobs.

Related errors

AI-assisted analysis of deepfakes/faceswap@f530cb7508 (2026-08-15). Data as JSON: /api/errors/f26c6f9917a7238b. Report an issue: GitHub.