Automatic1111 Error: 7 Real Fixes That Actually Work (2026)

Error	Quick Fix	Time
CUDA out of memory	Add --medvram or --lowvram to COMMANDLINE_ARGS, lower resolution/batch size	2 min
RuntimeError: Couldn’t install torch	Delete the venv folder and relaunch webui-user to rebuild it clean	5-10 min
Black or gray image output (NansException)	Add --no-half-vae, or --precision full --no-half on older cards	3 min
ImportError: cannot import name ‘packaging’ from ‘pkg_resources’	Pin setuptools inside the venv: pip install "setuptools<70"	3 min
UI breaks after updating (AttributeError / gradio errors)	Launch with --disable-all-extensions to isolate a bad extension	5-10 min
Can’t create/activate venv (Linux)	Install python3-venv/python3.10-venv and fix folder permissions	5 min
xformers won’t install or isn’t applying	Run with --reinstall-xformers or switch to --opt-sdp-attention	5-10 min

If you’ve spent an evening staring at a wall of red text in your terminal instead of generating images, you’re not alone. Automatic1111’s WebUI is one of the most powerful tools in the Stable Diffusion ecosystem, but it’s also a Python project held together by a venv, a pile of pinned dependencies, and whatever CUDA build happens to be on your system that week. One driver update, one extension install, or one checkpoint that’s slightly too big for your VRAM, and you’re suddenly debugging a stack trace instead of making art.

The good news is that almost every error this tool throws has a known cause and a specific fix — most of them are documented somewhere in the project’s GitHub issues or discussions, just scattered across hundreds of threads. This guide pulls the real fixes together in one place: actual command-line flags, actual file edits, and the actual reasoning behind why each error happens, so you’re not just copy-pasting a random flag and hoping.

What Causes Automatic1111 Errors

Not enough VRAM for what you’re asking it to do. This is the single biggest source of crashes. A 4GB or 6GB card can absolutely run SD 1.5, but push the resolution up, switch to SDXL, add a high-res fix pass, or run a large batch, and PyTorch will throw CUDA out of memory the moment allocation exceeds what’s physically on the GPU.

A stale or half-broken virtual environment. The venv folder is where every Python dependency lives. A failed update, an interrupted pip install, or a mismatched torch/CUDA pairing inside that venv causes launch failures and import errors that have nothing to do with your actual settings.

Extension and dependency drift. Third-party extensions each pin their own package versions. When one extension quietly bumps gradio, numpy, or pillow to a version the core WebUI doesn’t expect, you get AttributeErrors and blank UI panels that look like a core bug but are actually an extension fight.

Mismatched torch, CUDA, and xformers builds. xformers in particular is compiled against a specific torch and CUDA version. Update one without the other and you’ll get import failures or xformers silently falling back to unoptimized attention, sometimes with no error at all — just a slowdown or an OOM that shouldn’t be happening.

Precision issues on older or unusual GPUs. Cards like the GTX 16-series don’t support fp16 the way newer RTX cards do. Running the WebUI’s default half-precision settings on that hardware is the classic recipe for the NaN-tensor black-image bug.

Quick Fix — Try This First

Before you go chasing a specific error, open webui-user.bat (Windows) or webui-user.sh (Linux/Mac) in a text editor and find the line that says set COMMANDLINE_ARGS= (or export COMMANDLINE_ARGS="" on Linux). Set it to:

set COMMANDLINE_ARGS=--xformers --medvram

Save the file and relaunch. This single edit fixes a surprising share of the problems people run into: --xformers switches to a more memory-efficient attention implementation, and --medvram keeps the model split across CPU/GPU so it doesn’t try to hold everything in VRAM at once. It’s not a fix for every error on this page, but if you haven’t touched your launch args at all, this is the fastest way to rule out the most common cause before digging further.

Step-by-Step Fix Guide

Step 1: Confirm it’s actually a VRAM problem, then size your args to your card

If your error message includes torch.cuda.OutOfMemoryError or RuntimeError: CUDA out of memory. Tried to allocate ... GiB, you’re VRAM-limited, not broken. Check how much VRAM is actually free with nvidia-smi in a terminal — other apps (browser tabs with hardware acceleration, other GPU processes) eat into what the WebUI can use. Then match your flags to your card:

• 8GB and up, mostly SDXL: --medvram-sdxl (only applies medvram behavior when an SDXL model is loaded, keeps SD1.5 fast)
• 4-8GB: --medvram
• Under 4GB: --lowvram (much slower, but it’ll run)

Also drop your batch size to 1, lower resolution before using hires fix, and disable “Move VAE and CLIP to RAM” style settings only if you have RAM to spare. If OOM errors happen intermittently rather than every time, add this line above your COMMANDLINE_ARGS in webui-user:

set PYTORCH_CUDA_ALLOC_CONF=garbage_collection_threshold:0.6,max_split_size_mb:128

This reduces memory fragmentation in PyTorch’s allocator, which is a real and common cause of OOM errors that happen even when nvidia-smi shows free VRAM.

Step 2: Rebuild a clean venv when the WebUI won’t launch at all

Errors like RuntimeError: Couldn't install torch almost always trace back to a corrupted venv, not your internet connection, even though the traceback makes it look network-related. The fix that resolves this most reliably: close the WebUI, delete the venv folder inside your stable-diffusion-webui directory entirely, and relaunch webui-user.bat/webui-user.sh. It will rebuild the environment from scratch and reinstall torch using the URLs baked into launch.py.

# Windows (from the webui folder)
rmdir /s /q venv
webui-user.bat

# Linux/Mac
rm -rf venv
./webui.sh

If it still fails to install torch after a clean venv, check that you’re on Python 3.10.x – the project has long recommended 3.10.6 specifically, and newer 3.12/3.13 installs have caused install failures with some torch/xformers wheel combinations. Also check whether you’re behind a proxy or firewall that’s blocking pip’s connection to PyPI or the PyTorch index.

Step 3: Fix black or gray image output (NansException)

If your console shows NansException: A tensor with all NaNs was produced in Unet (or in VAE) and your output image is solid black or gray, this is a precision problem, not a corrupted install. It shows up most on GTX 16-series cards and some other GPUs that don’t handle fp16 cleanly, and it can also show up on SDXL when the VAE itself produces NaNs. Try these in order:

• If it’s happening specifically in VAE decoding (image is black but generation “succeeded”): add --no-half-vae
• If it’s happening in the UNet more broadly: add --precision full --no-half (uses significantly more VRAM, so combine with --medvram)
• If you’re on SDXL, also try swapping to the fixed SDXL VAE (madebyollin’s fp16-fix VAE) via the VAE dropdown in Settings — a broken or mismatched VAE file is a common root cause

As a last-resort workaround (not a real fix, just gets you unstuck), --disable-nan-check skips the check entirely and lets the pipeline continue — useful for confirming NaNs are really the cause, but you’ll often just get garbage output instead of a crash.

Step 4: Fix “ImportError: cannot import name ‘packaging’ from ‘pkg_resources'”

This one trips people up because it looks like a core WebUI bug, but it’s a setuptools compatibility break — newer setuptools releases removed the vendored pkg_resources.packaging shim that older install scripts (including some in the WebUI’s dependency chain) still import. The fix is to pin setuptools to a working version inside your venv:

# Windows
venv\Scripts\python.exe -m pip install "setuptools<70"

# Linux/Mac
venv/bin/python -m pip install "setuptools<70"

Relaunch after that. If you’d rather not hand-edit the venv, deleting the venv folder (Step 2) and letting it rebuild from the pinned requirements_versions.txt also resolves it in most cases, since that file locks known-good versions.

Step 5: Isolate a bad extension after an update

If the WebUI launched fine yesterday and today you’re getting AttributeError messages referencing gradio, or the UI loads with blank tabs/missing buttons, an extension update is almost always the cause — extensions get updated independently of the core app and can pull in package versions the WebUI doesn’t expect. Relaunch with all extensions disabled to confirm:

set COMMANDLINE_ARGS=--disable-all-extensions

If the WebUI comes up clean, the problem is an extension. Re-enable them one at a time (or move folders out of the extensions directory one at a time) to find the culprit, then either update it, roll it back to a previous commit via git, or remove it. If you only want to rule out third-party extensions while keeping built-in ones, use --disable-extra-extensions instead.

Step 6: Fix venv creation/activation failures on Linux

“Cannot activate python venv, aborting” or errors during first launch on Linux almost always mean the venv module itself isn’t installed for your Python version — it’s a separate OS package, not something pip pulls in. Install it and clear any partial venv before retrying:

sudo apt install python3.10-venv
rm -rf venv
./webui.sh

On some distros you’ll need the exact versioned package (python3.10-venv, not just python3-venv) to match whatever Python version webui.sh is calling. Also check that the folder isn’t owned by root if you previously ran anything with sudo — permission mismatches on the venv directory cause the same error.

Advanced Fixes

Once you’re past the common errors, these are the flags and edits worth knowing for deeper troubleshooting. All of these go into COMMANDLINE_ARGS in webui-user, and can be combined on one line:

set COMMANDLINE_ARGS=--xformers --medvram --no-half-vae --skip-torch-cuda-test

• --opt-sdp-attention or --opt-sdp-no-mem-attention — PyTorch 2.0+’s built-in scaled dot-product attention. Worth trying if xformers refuses to install cleanly; performance is close to xformers on most cards without the separate build dependency.
• --skip-torch-cuda-test — bypasses the startup check that verifies torch can see your GPU. Useful on unusual setups (some AMD/DirectML configs, certain WSL setups) where the check itself fails even though generation would actually work.
• --reinstall-torch / --reinstall-xformers — forces a fresh reinstall of just that package on next launch without wiping the whole venv. Faster than a full venv rebuild when you suspect one specific package is the problem.
• --skip-install — skips the dependency-check/install step entirely on launch, which speeds up startup once your environment is known-good, and is also handy for isolating whether an error is coming from the install step or from actual generation.
• Pin an exact torch/xformers pair manually when auto-install keeps grabbing an incompatible combination:

venv\Scripts\python.exe -m pip install torch==2.1.2+cu121 torchvision==0.16.2+cu121 --index-url https://download.pytorch.org/whl/cu121
venv\Scripts\python.exe -m pip install xformers==0.0.23.post1

Adjust the version numbers to match your actual CUDA driver version (check with nvidia-smi — the CUDA version listed there is the ceiling for what wheel you can install) and check requirements_versions.txt in the repo root for the pairing the current codebase expects.

Still Not Working? Try These Instead

If you’ve worked through the fixes above and you’re still fighting your install more than you’re using it, it might genuinely be time to consider an alternative — development on forks has outpaced the original A1111 repo in some areas over the past couple of years.

• Forge (lllyasviel) — a drop-in replacement built on the same WebUI foundation, with a rewritten memory management backend that handles low-VRAM situations and SDXL noticeably better out of the box, and far fewer of the dependency headaches covered above.
• ComfyUI — a node-based interface that trades A1111’s simplicity for granular control over the pipeline. Steeper learning curve, but its dependency handling is generally more stable and it tends to get support for new models faster.
• Fooocus — aimed at people who just want good images with minimal configuration. Far fewer knobs than A1111, but almost none of the setup fragility either — a reasonable fallback if you just want something that works today.

FAQ

Is Automatic1111’s WebUI still worth using in 2026?

Yes, for a lot of people it still is — it’s stable, extremely well documented after years of community use, and has the largest extension ecosystem of any Stable Diffusion UI. That said, active development on the core repo has slowed compared to forks like Forge, so if you’re hitting frequent compatibility issues with newer models, it’s worth trying one of the alternatives above rather than fighting the install.

Why does xformers keep failing to install?

xformers ships as prebuilt wheels tied to specific torch and CUDA versions. If your venv has a torch version that doesn’t have a matching xformers wheel available, pip will either fail outright or silently fall back. Run --reinstall-xformers after confirming your torch version, or just use --opt-sdp-attention instead — it doesn’t require a separate matched build and performs close enough to xformers on modern cards.

What Python version should I use?

Python 3.10.6 is the version the project has been built and tested against for the longest, and it’s still the safest choice for compatibility with pinned dependencies. Python 3.11 and 3.12 mostly work now but have historically caused wheel-availability issues for torch and xformers — if you’re troubleshooting an install failure, checking your Python version is a quick thing to rule out.

How do I completely reset my installation without losing my models?

Your checkpoints, LoRAs, and outputs live outside the venv (in models/ and outputs/), so they’re safe. Delete the venv folder and, if you want a truly clean slate, also delete repositories/ — both get rebuilt automatically on next launch without touching your model files.

Why do I get different errors after every git pull?

Pulling the latest commit can bump the expected versions in requirements_versions.txt out from under an existing venv that hasn’t been rebuilt. After any update, if you hit an unfamiliar import error, deleting the venv and letting it reinstall against the new requirements file resolves the mismatch far more often than trying to manually patch individual packages.