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?
dfdcbabEvidence checked 24 Aug 2026Runtime: source-audited · no GPU reproductionDo 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 this provesThe configured executable did not run. A separate system Python does not prove 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 this provesAt inspected 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 this provesForge 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 this provesThe 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 this provesThe 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 verified 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 this provesTorch 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 unverified until tested.
- Do not do this
- Do not hide the architecture error with memory flags, --skip-version-check, or a different model.
What this provesNumPy 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 be a diagnostic, but it is not proof the remaining environment is 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 this provesThe 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 a dated default, not a universal hardware matrix.
Verify official wheels ↗1.26.2
The inspected requirements file pins NumPy 1.26.2. Seeing NumPy 2.x in this environment is evidence 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 prove GPU support, but conflicts are actionable evidence.
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 evidence
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 dated evidence 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 verified 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 prove 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 proof 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 verified 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 ↗A named package is evidence, 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 evidence 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 original Forge use?
At the inspected 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 snapshot.
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 verified venv and let Forge create a new one from the correct base Python. Treat the old environment as evidence, 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 verified 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 evidence.
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 original Forge support RTX 50-series GPUs?
The original dated archives cannot be treated as proof. Community reports describe custom newer Torch stacks, but there is no single verified 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 snapshot. 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 original-repository identity, 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.
Current code sets the baseline. Reports define the symptom vocabulary.
Community fixes are not silently promoted to product requirements. Dated videos show where users encounter the environment; they do not override current code or upstream documentation.
Community reports · 6 records
- Issue #3012 2025 user report: package Python path / exit code 9009 symptom.
- Issue #3017 2025 user report reproducing the current incompatible-Python warning.
- Issue #2969 2025 user report: NumPy 2.x ABI messages inside a Forge venv.
- Issue #2746 2025 open question and community experiments for RTX 50-series.
- Issue #1998 2024 user report: missing python3-venv on Linux.
- Issue #1663 2024 user report: traceback resolving packages from another WebUI venv.