Fix the environment layer that actually failed
A CUDA-looking traceback can begin with the wrong Python. A successful pip install can modify a different environment. Read the exact interpreter and first failed layer before replacing anything.
- 01LauncherCan the batch or shell script execute the configured Python?↓
- 02InterpreterIs this the intended Python version, architecture, and executable?↓
- 03Virtual environmentDoes Forge use its own venv rather than another application’s packages?↓
- 04Package setDo Torch, NumPy, xformers, transformers, and compiled wheels agree?↓
- 05Device pathCan this exact Torch build initialize the intended accelerator?
Do not start with CUDA.
Start with the executable that Forge actually launched. If Python cannot run, repair its path. If the venv cannot form, repair the base interpreter. If imports fail, restore the package set. Only then decide whether Torch and the driver can use the device.
--skip-python-version-check, --skip-torch-cuda-test, and --skip-version-check can bypass checks. They do not supply a compatible interpreter, wheel, driver, compiled GPU architecture, or NumPy ABI.
Choose the first meaningful error.
Use the earliest complete message, not the final “Press any key” line or the error produced by a later attempted fix.
What it meansThe configured executable did not run. A separate system Python does not guarantee the package’s embedded Python path or a Git checkout’s PYTHON setting is valid.
- Read-only test
- Preserve stdout/stderr. For Git, inspect the PYTHON line in webui-user.bat and run that exact executable with --version. For the package, confirm the embedded path echoed by its launcher still exists.
- Controlled repair
- Restore the correct path for the install route. If the package was moved or incompletely extracted, compare a separate complete extraction instead of installing packages globally.
- Do not do this
- Do not install Torch, CUDA, or NumPy until the intended Python executable itself runs.
What it meansAt current main, Forge accepts only Python 3.10 on Windows and prints 3.10.6 as tested. Suppressing the check does not change which wheels exist for that interpreter.
- Read-only test
- Compare the console header, sys.executable, sys.version, and the base interpreter recorded in venv\pyvenv.cfg.
- Controlled repair
- On the controlled Windows Git route, set PYTHON to the intended 64-bit Python 3.10 executable, preserve the old venv by renaming it, then let Forge create a new one.
- Do not do this
- --skip-python-version-check hides the warning; it is not a dependency compatibility fix.
What it meansForge has not reached its package or GPU tests. The base interpreter, venv module, permissions, path, or free space failed first.
- Read-only test
- Run the selected base Python with -c "import venv; print(venv.__file__)" and preserve the launcher’s first stderr. On Linux, confirm the distribution’s matching venv package is present.
- Controlled repair
- Fix that prerequisite, then recreate only the Forge-local environment. Python documents venvs as disposable and non-portable; moving a parent folder can invalidate embedded paths.
- Do not do this
- Do not copy a venv from A1111, another computer, or an old Forge location.
What it meansThe installation command failed. The first pip error can name an unavailable wheel, Python mismatch, network/certificate problem, disk problem, or dependency conflict.
- Read-only test
- Record Python, OS, architecture, the complete TORCH_COMMAND/index URL, and the first pip error—not only the final RuntimeError.
- Controlled repair
- Return to a supported Forge baseline or validate a custom Torch build in a separate clean checkout. Current main defaults to Torch 2.3.1 / torchvision 0.18.1 from the CUDA 12.1 index.
- Do not do this
- Do not paste a nightly command from a different GPU, OS, Python, or Forge fork into a working environment.
What it meansThe loaded Torch cannot use CUDA in this process. torch.version.cuda and torch.cuda.is_available() distinguish a CPU wheel from a CUDA wheel that cannot initialize.
- Read-only test
- Run the probe with Forge’s exact interpreter, then compare nvidia-smi, the loaded Torch version, wheel CUDA value, and CUDA availability.
- Controlled repair
- For NVIDIA, restore a compatible CUDA-enabled Torch build and driver combination for the exact GPU. For AMD, Intel, or Apple, stop treating CUDA as the required backend and use a separately confirmed platform route.
- Do not do this
- --skip-torch-cuda-test bypasses Forge’s launch assertion; it does not compile CUDA support or make a GPU visible.
What it meansTorch may see the GPU but the installed binaries may not contain code for its compute capability. The August 2024 Forge archives cannot be assumed to cover later hardware.
- Read-only test
- Record the exact GPU, driver, error, torch.cuda.get_device_capability(), and torch.cuda.get_arch_list(). PyTorch defines the latter as the architectures compiled into the library.
- Controlled repair
- Check current PyTorch and NVIDIA support for that architecture. If Forge needs a newer stack, build a separate controlled environment and treat Forge/xformers compatibility as untested until tested.
- Do not do this
- Do not hide the architecture error with memory flags, --skip-version-check, or a different model.
What it meansNumPy documents these messages as binary incompatibility between NumPy and a downstream compiled package. Current Forge main pins NumPy 1.26.2.
- Read-only test
- Use Forge’s exact interpreter to print NumPy’s version. Read the traceback backward to the first package outside NumPy and record that package version too.
- Controlled repair
- Prefer restoring the complete pinned Forge environment or rebuilding a clean venv. A one-package downgrade can help diagnose the issue, but it does not make the rest of the environment consistent.
- Do not do this
- Do not run a bare global pip install: the wrong interpreter can report success while Forge continues using another NumPy.
What it meansThe traceback names incompatible package versions or a missing compiled library. Shared venvs and extension installers can change the environment without changing the Forge commit.
- Read-only test
- Run python -m pip check with the Forge interpreter, save python -m pip freeze, and repeat once with third-party extensions disabled.
- Controlled repair
- Compare against requirements_versions.txt at the same Forge commit. A clean Forge-local venv is a stronger baseline than manually pinning each package named by successive tracebacks.
- Do not do this
- Do not follow the traceback’s generic “pip install -U” suggestion without checking Forge’s pinned versions and environment boundary.
One source commit can run through different package states.
A Git hash identifies Forge source. It does not identify Python, every installed wheel, the GPU driver, or extension mutations.
3.10.x accepted
Current main accepts only minor version 3.10 on Windows and names 3.10.6 as tested. The skip flag suppresses its warning only.
Inspect the check ↗2.3.1 · cu121 index
Current main’s default command pairs Torch 2.3.1 with torchvision 0.18.1. It is an earlier default, not a universal hardware matrix.
Verify official wheels ↗1.26.2
The current requirements file pins NumPy 1.26.2. Seeing NumPy 2.x in this environment shows that its package state drifted.
Inspect requirements ↗torch.cuda.is_available()
Forge uses this boolean for its default CUDA gate. Bypassing it changes the gate, not the underlying result.
Read the API definition ↗Ask Forge’s Python, not whichever pip opens first.
These commands print state; they do not install or remove anything. Run them from the Forge folder after stopping generation.
venv\Scripts\python.exeUse after webui.bat created the local venv. If it does not exist, diagnose Python/venv creation before Torch.
- 01
venv\Scripts\python.exe -c "import sys; print(sys.executable); print(sys.version); print(sys.prefix); print(sys.base_prefix)" - 02
venv\Scripts\python.exe -c "import torch, numpy; print('torch', torch.__version__); print('wheel CUDA', torch.version.cuda); print('CUDA available', torch.cuda.is_available()); print('NumPy', numpy.__version__)" - 03
venv\Scripts\python.exe -m pip check
system\python\python.exeUse this only if that path exists in your extracted package. Otherwise copy the exact Python path printed by the package console; do not substitute system pip.
- 01
system\python\python.exe -c "import sys; print(sys.executable); print(sys.version); print(sys.prefix); print(sys.base_prefix)" - 02
system\python\python.exe -c "import torch, numpy; print('torch', torch.__version__); print('wheel CUDA', torch.version.cuda); print('CUDA available', torch.cuda.is_available()); print('NumPy', numpy.__version__)" - 03
system\python\python.exe -m pip check
venv/bin/pythonThe current webui.sh defaults to a local venv. Linux accelerator packages remain hardware- and distribution-specific; this probe only identifies the loaded environment.
- 01
venv/bin/python -c "import sys; print(sys.executable); print(sys.version); print(sys.prefix); print(sys.base_prefix)" - 02
venv/bin/python -c "import torch, numpy; print('torch', torch.__version__); print('wheel CUDA', torch.version.cuda); print('CUDA available', torch.cuda.is_available()); print('NumPy', numpy.__version__)" - 03
venv/bin/python -m pip check
sys.executable is the authority.If it points outside this Forge route, stop and repair isolation.
torch.version.cuda names the build runtime.None means the loaded Torch wheel is not CUDA-enabled.
is_available() reports current access.false needs the first initialization error, not a guessed version.
pip check finds declared conflicts.A clean result does not guarantee GPU support, but conflicts are actionable details.
Rebuild one boundary at a time.
Preserve the old environment long enough to explain the difference. A clean rebuild is useful only when its interpreter, source, and extensions are controlled.
- 01
Freeze the details
Save the complete console, install route, Forge commit, launch arguments, GPU, driver, and whether the same folder worked before. Do not update source and packages yet.
- 02
Name the exact interpreter
Use the route-specific path above. sys.executable must identify the Python actually running Forge; a successful global python or pip command is irrelevant if the paths differ.
- 03
Classify the first failed layer
Launcher and venv errors come before package repair. Import/ABI errors come before device tuning. CUDA OOM belongs to the memory diagnostic, not this page.
- 04
Test without extensions
Run one baseline with --disable-all-extensions. This prevents third-party installers from being treated as part of the core package set.
- 05
Rebuild, do not mutate blindly
For a Git checkout with the correct base Python, stop Forge, rename venv to a backup folder, and relaunch. Do not reuse the renamed venv; compare it only.
WINDOWS GIT · PRESERVEren venv venv.before-env-rebuildTHEN RECREATEwebui-user.bat - 06
Keep custom Torch separate
If the official/detected stack cannot support the GPU, create a separate Git checkout and environment. Record TORCH_COMMAND, index, Python, driver, and every changed pin.
- 07
Prove the done state
The same interpreter imports Torch and NumPy, pip check has no unexplained conflicts, the intended device is available, Forge starts without extensions, and one baseline generation completes.
Four CUDA numbers can describe four different things.
The driver, Torch wheel, compiled architecture list, and current availability answer different questions. Record them without forcing them to match as text.
| Signal | What it means | Controlled action | False shortcut |
|---|---|---|---|
| Python version warning | Interpreter does not match the launcher’s accepted/tested range. | Select the correct base Python and rebuild the Forge-local venv. | --skip-python-version-check only hides the warning. |
| torch.version.cuda is None | A CPU-only Torch build is loaded. | Confirm the install route and use a confirmed accelerator build for the platform. | Installing a system CUDA Toolkit does not turn a CPU wheel into a CUDA wheel. |
| torch.version.cuda has a value; is_available() is false | A CUDA build loaded but cannot use a visible device now. | Read the first initialization error; check GPU visibility and driver compatibility. | The version number alone does not guarantee runtime availability. |
| nvidia-smi shows “CUDA Version” | The driver reports the maximum CUDA version it supports. | Compare it with the wheel runtime and current compatibility documentation. | It is not the installed Torch version or test that Forge loaded CUDA. |
| Unsupported sm_* / no kernel image | The binary lacks suitable compiled architecture code or cannot execute it. | Compare device capability with the build’s arch list and supported PyTorch release. | Memory flags and model changes cannot add compiled kernels. |
| AMD / Intel / Apple device | CUDA is not the correct universal backend. | Use the platform’s separately confirmed ROCm, XPU/IPEX, MPS, DirectML, or CPU route. | A CUDA archive and skip flag do not establish support. |
nvidia-smi is a driver signal.NVIDIA documents that its displayed CUDA version is the maximum supported by the driver. Compare it with the runtime used by the loaded Torch wheel; do not call the two values a conflict solely because they differ.
Open NVIDIA’s matrix ↗One package error is not an invitation to upgrade everything.
Extension installers, a shared environment, a custom command, or an interrupted repair can change wheels while the Forge commit stays the same.
Forge checks its pinned requirements.
The launcher compares exact pinned versions and installs requirements_versions.txt when they do not match. The file currently pins NumPy 1.26.2, transformers 4.46.1, pydantic 2.8.2, and other application packages.
A Forge venv was running NumPy 2.2.6.
Issue #2969 shows _ARRAY_API and dtype size changed errors with NumPy 2.2.6. It demonstrates the symptom and drift—not a universal cause or approved one-line repair.
A traceback resolved through an A1111 venv.
Issue #1663 shows a Forge traceback importing tokenizers from another WebUI environment. Separate environments prevent this class of ambiguity.
A traceback may suggest pip install -U. First identify the interpreter, compare the same-commit pins, disable extensions, and decide whether a clean Forge-local rebuild is safer than another in-place mutation.
Translate the message into one next test.
Different tracebacks can share a recovery procedure. This is why they belong on one canonical diagnostic page instead of one thin page per error string.
Couldn’t launch python · exit code 9009
The launcher could not execute its configured Python. Confirm the exact path before investigating packages.
INCOMPATIBLE PYTHON VERSION
The current interpreter is outside Forge’s accepted range for that OS. The warning itself identifies both actual and expected versions.
ERROR: python3-venv is not installed
The POSIX launcher cannot import the venv module. Install the matching distribution package for the selected Python, then recreate the local environment.
RuntimeError: Couldn’t install torch
Scroll up to the first pip resolution, wheel, network, certificate, or disk error. The RuntimeError is only the wrapper.
Your device does not support the current version of Torch/CUDA
Current Forge raises this when import torch succeeds but torch.cuda.is_available() fails, unless the check is deliberately skipped.
AssertionError: Torch not compiled with CUDA enabled
The running process reached CUDA code with a Torch build/backend that cannot provide CUDA. Verify the exact interpreter and wheel first.
no kernel image is available for execution on the device
The GPU may be visible while the binaries lack code for its architecture. Record capability and compiled arch list.
AttributeError: _ARRAY_API not found
A downstream binary was built against an incompatible NumPy ABI. Find the first non-NumPy package in the traceback.
ValueError: numpy.dtype size changed
NumPy documents this as binary incompatibility, not a model, sampler, or VRAM error.
tokenizers / transformers version requirement
The package set drifted. Generic upgrade text comes from that library and may conflict with Forge’s pinned requirements.
xformers cannot load C++/CUDA extensions
Treat Torch, Python, CUDA build, and xformers as one compatibility group; do not upgrade only the last package without recording the stack.
Make the next test reproducible.
Complete this before opening an issue or declaring a package version fixed.
Environment details complete. Change one boundary, rerun the same probe, and record the new result beside the old one.
Answers before another pip command.
These questions cover the language users type when Python, venv, NumPy, Torch, CUDA, xformers, or a new GPU stops Forge.
How do I fix “Couldn’t launch python” in Forge?
First make the configured executable run. A Windows Git checkout can set PYTHON in webui-user.bat; the official package should use its own extracted Python path. Preserve error 9009 or stderr before changing packages.
What does Forge exit code 9009 mean?
In reported Windows cases it accompanies “Couldn’t launch python,” meaning the batch launcher could not execute the configured command. Verify the exact embedded or configured Python path; do not begin with CUDA.
Which Python version should Forge use?
At the current main commit, Windows accepts Python 3.10.x and the launcher says it was tested with 3.10.6. Non-Windows code accepts a wider range, but a controlled 3.10 environment remains the documented baseline for this version.
Does --skip-python-version-check fix Forge?
No. It suppresses the compatibility warning only. It does not create missing wheels, change the interpreter, or repair a venv built with a different Python.
Why can Forge not create or activate venv?
Check the selected base Python, import venv, write permission, free space, and the first launcher stderr. On Linux, the matching python3-venv package may be missing.
Should I delete the Forge venv?
Not before recording the failing environment. For a Git checkout, rename the confirmed venv and let Forge create a new one from the correct base Python. Treat the old environment as details, not as reusable backup.
Why did Forge stop working after I moved its folder?
Python documents virtual environments as non-portable because scripts contain absolute interpreter paths. Recreate the venv at the new location instead of copying or continuing to repair the moved environment.
How do I find which Python Forge actually uses?
Run sys.executable through the exact interpreter path used by the install route. Also record sys.prefix and sys.base_prefix; a venv normally has different values for those prefixes.
How do I fix “Couldn’t install torch” in Forge?
Save the first pip error, Python version, OS, GPU, driver, and full Torch command/index. Restore the known Forge baseline or test a confirmed alternate stack in a separate checkout; the final RuntimeError is not the root cause.
What does “Torch not compiled with CUDA enabled” mean?
The loaded Torch build cannot provide CUDA to that process. Check torch.version.cuda using Forge’s interpreter. If it is None, a CPU build loaded; if it has a value, continue with availability and initialization details.
Why does Forge say my device does not support the current Torch/CUDA version?
Current Forge raises that message when its torch.cuda.is_available() test fails. It can reflect the wrong wheel, driver/visibility failure, unsupported hardware, or a non-CUDA platform; the message alone does not choose the repair.
Why is torch.cuda.is_available() false?
It only reports whether CUDA is currently available to that Torch process. Compare the exact interpreter, Torch build, wheel CUDA value, driver, visible device, and first initialization error.
Why do nvidia-smi and Torch show different CUDA versions?
nvidia-smi reports the maximum CUDA version supported by the installed driver, while torch.version.cuda describes the runtime used to build the loaded Torch wheel. They are related compatibility signals, not the same installation record.
Do I need to install the full CUDA Toolkit for Forge?
Not normally for the official prebuilt PyTorch wheel/package route. The wheel supplies its runtime components and needs a compatible NVIDIA driver. Building packages or using a custom stack can introduce toolkit requirements.
How do I fix “no kernel image is available” or unsupported sm_120?
Record the GPU capability and Torch compiled architecture list. Then verify a PyTorch build that supports the hardware. Because Forge’s official archives were uploaded in August 2024, do not assume they support later GPU architectures.
Does Forge support RTX 50-series GPUs?
The original earlier archives cannot be treated as test. Community reports describe custom newer Torch stacks, but there is no single confirmed command here that guarantees Forge, xformers, extensions, and every RTX 50-series model work together.
How do I fix NumPy _ARRAY_API not found in Forge?
Use Forge’s interpreter to record NumPy and the first failing downstream package. Current main pins NumPy 1.26.2. Prefer restoring the complete pinned environment or a clean venv over changing global NumPy.
What does “numpy.dtype size changed” mean?
NumPy documents it as binary incompatibility between NumPy and a compiled downstream module. It is not an OOM, model, or sampler error.
Why does pip say it installed a package but Forge still sees the old version?
You probably ran pip through another interpreter. Use the Forge executable followed by -m pip so the package command and the running application share one Python.
Should I run pip install -U when transformers or tokenizers asks?
Not blindly. That generic suggestion does not know Forge’s requirements version. Record the versions, run pip check, compare the same-commit requirements file, and rebuild a clean Forge-local environment if the set drifted.
How do I fix an xformers Torch or CUDA mismatch?
Treat Python, Torch, CUDA runtime, GPU architecture, and xformers as one compiled compatibility group. Restore a known matching environment or test a documented replacement in a separate checkout.
Can --skip-torch-cuda-test make Forge use my GPU?
No. It only bypasses Forge’s availability assertion. It cannot turn a CPU wheel into a CUDA wheel, update the driver, add compiled GPU architectures, or create another platform backend.
Can Forge share the AUTOMATIC1111 virtual environment?
The source exposes an advanced shared-venv option, but it weakens diagnosis because either application or extension can change the same packages. Use separate venvs for a reproducible baseline.
What should I include in a Forge Python or CUDA bug report?
Include repository URL, commit, install route, OS, exact GPU and driver, sys.executable/version/prefixes, Torch and wheel CUDA versions, CUDA availability, NumPy and named package versions, pip check, full first traceback, arguments, extension-disabled result, and clean-environment result.