{"record":{"id":"f26c6f9917a7238b","repo":"deepfakes/faceswap","slug":"faceswap-ran-out-of-ram-running-convert-conversio","errorCode":null,"errorMessage":"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).","messagePattern":"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\\)\\.","errorType":"exception","errorClass":"FaceswapError","httpStatus":null,"severity":"critical","filePath":"scripts/convert.py","lineNumber":248,"sourceCode":"        \"\"\"\n        logger.debug(\"Starting Conversion\")\n        # queue_manager.debug_monitor(5)\n        try:\n            self._convert_images()\n            self._disk_io.save_thread.join()\n            queue_manager.terminate_queues()\n\n            finalize(self._images.count,\n                     self._predictor.faces_count,\n                     self._predictor.verify_output)\n            logger.debug(\"Completed Conversion\")\n        except MemoryError as err:\n            msg = (\"Faceswap ran out of RAM running convert. Conversion is very system RAM \"\n                   \"heavy, so this can happen in certain circumstances when you have a lot of \"\n                   \"CPUs but not enough RAM to support them all.\"\n                   \"\\nYou should lower the number of processes in use by either setting the \"\n                   \"'singleprocess' flag (-sp) or lowering the number of parallel jobs (-j).\")\n            raise FaceswapError(msg) from err\n\n    def _convert_images(self) -> None:\n        \"\"\"Start the multi-threaded patching process, monitor all threads for errors and join on\n        completion.\"\"\"\n        logger.debug(\"Converting images\")\n        self._patch_threads.start()\n        while True:\n            self._check_thread_error()\n            if self._disk_io.completion_event.is_set():\n                logger.debug(\"DiskIO completion event set. Joining Pool\")\n                break\n            if self._patch_threads.completed():\n                logger.debug(\"All patch threads completed\")\n                break\n            sleep(1)\n        self._patch_threads.join()\n\n        logger.debug(\"Putting EOF\")","sourceCodeStart":230,"sourceCodeEnd":266,"githubUrl":"https://github.com/deepfakes/faceswap/blob/f530cb7508ae670f6474f8a7d9c4df94705cf96b/scripts/convert.py#L230-L266","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"# before\npython faceswap.py convert -i in -o out -m /models/m -j 16\n\n# after\npython faceswap.py convert -i in -o out -m /models/m -j 2\n# or single process:\npython faceswap.py convert -i in -o out -m /models/m -sp","handlingStrategy":"fallback","validationCode":"# before launching convert, sanity-check RAM vs job count (rule of thumb)\nimport os\nfree_gb = os.sysconf('SC_PAGE_SIZE') * os.sysconf('SC_AVPHYS_PAGES') / 2**30\nif args.jobs and args.jobs > 1 and free_gb < 2.0 * args.jobs:\n    print(f\"WARNING: ~{free_gb:.1f}GB free for {args.jobs} jobs; consider -j 1 or -sp\")","typeGuard":null,"tryCatchPattern":"from lib.exceptions import FaceswapError\ntry:\n    convert.process()\nexcept FaceswapError as err:\n    if \"out of RAM\" in str(err):\n        rerun_convert(singleprocess=True)  # fallback with -sp\n    else:\n        raise","preventionTips":["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"],"tags":["faceswap","convert","memory","processes"],"backgroundTag":null,"analyzedSha":"f530cb7508ae670f6474f8a7d9c4df94705cf96b","analyzedAt":"2026-08-15T02:59:26.626Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}