Notice: This repository is no longer actively maintained and may contain outdated information.
This README serves as a comprehensive guide for installing LM Studio across macOS, Ubuntu Linux, and Windows. It also documents common known errors and their direct fixes, ensuring your local LLM environment runs as smoothly as possible.
LM Studio is a desktop application designed to run, manage, and interact with Large Language Models (LLMs) locally, keeping your data entirely on your device.
Before installing, ensure your hardware meets these baseline specifications:
- Operating System: Windows 10/11 (64-bit), macOS 12+, or Linux (Ubuntu 20.04+)
- RAM: Minimum 16 GB (32 GB highly recommended).
Tip
LM Studio can technically run on 8 GB of RAM if you are strictly using smaller, heavily quantized models (e.g., 3B or 7B parameters), but 16 GB is the recommended baseline to prevent out-of-memory crashes.
- Disk Space: At least 20 GB free space (model weights take up significant space)
- GPU: A dedicated NVIDIA, AMD, or Apple Silicon GPU is strongly recommended for hardware acceleration.
All official installers are available at the LM Studio website.
LM Studio ships separate builds for Apple Silicon and Intel to optimize hardware acceleration.
- Check your architecture (
Apple Menu > About This Mac). - Download the corresponding
.dmgfile:- Apple Silicon (M1/M2/M3/M4): Automatically uses Metal GPU acceleration.
- Intel (x86_64): GPU acceleration is generally limited to integrated graphics.
- Open the downloaded
.dmgfile. - Drag the LM Studio icon into your
Applicationsfolder. - Open the app from your Applications folder (you may need to approve a standard macOS security prompt on the first launch).
Windows uses a standard 64-bit installer. If your NVIDIA drivers are up to date, CUDA acceleration will be detected automatically.
- Download the
.exeinstaller for Windows.
Note
A portable .zip build is also available if you prefer not to write to the registry or want to run it from an external drive.
- Double-click the downloaded
.exe. - Follow the standard installation wizard.
- Once completed, launch LM Studio.
LM Studio for Linux is primarily distributed as an .AppImage or a .deb package.
- Download the Linux version from the official site.
- Open a terminal and navigate to your download directory.
- Make the
.AppImageexecutable by running:
chmod +x LM-Studio-*.AppImage
- Execute the application:
./LM-Studio-*.AppImage
Note
If you run into issues launching the AppImage, refer to the FUSE fix in the troubleshooting section below.
The Issue: When installing LM Studio via the .deb package on Ubuntu (versions like 24.04 or 26.04), the application shows up with a generic gear/blank icon instead of the official LM Studio logo.
The Cause: The package mistakenly installs the icon into an invalid 0x0 directory (/usr/share/icons/hicolor/0x0/apps/lm-studio.png). GNOME ignores folders named 0x0.
The Fix: You need to copy the icon to a standard directory and update the icon cache. Run the following commands in your terminal:
sudo cp /usr/share/icons/hicolor/0x0/apps/lm-studio.png /usr/share/icons/hicolor/256x256/apps/
sudo gtk-update-icon-cache -f /usr/share/icons/hicolor/
Tip
Alternatively, you can copy it to /usr/share/pixmaps/lm-studio.png. Once done, restart LM Studio or your GNOME session, and the logo will appear.
The Issue: Running the .AppImage fails immediately with an error regarding FUSE or dlopen.
The Cause: Modern Ubuntu releases no longer ship with libfuse2 by default, which is required by many AppImages.
The Fix: Install the missing FUSE library:
sudo apt update
sudo apt install libfuse2
After installation, try running the AppImage again. No reboot is required.
The Issue: Models run incredibly slowly (under 2 tokens per second), and the GPU layers slider shows 0 VRAM.
The Cause: LM Studio relies on platform-specific APIs (CUDA for NVIDIA, ROCm for AMD). If it fails silently, it defaults to your CPU.
The Fix (NVIDIA/Windows): Standard Windows Update graphics drivers are often insufficient. Download and install the latest "Game Ready" or "Studio" driver directly from NVIDIA's website. Restart your PC.
The Fix (AMD/Linux): Ensure you have installed the correct ROCm version for your distribution. Additionally, make sure your user account has permissions to access the GPU by adding yourself to the render and video groups:
sudo usermod -aG render $USER
sudo usermod -aG video $USER
Restart your system to apply group changes.
Note
If AMD drivers recently updated on Windows and broke LM Studio, deleting the ~/.lmstudio/backend folder temporarily resolves the detection loop without needing a clean driver install.
The Issue: Clicking "Start Server" fails, or the server status stays red.
The Cause: By default, LM Studio attempts to bind to port 1234. Another application on your machine may already be using this port.
The Fix: Go to the Server tab in LM Studio and change the port from 1234 to an unused port, such as 1235 or 8080. Alternatively, find the conflicting process and kill it:
- Windows:
netstat -ano | findstr :1234 - Mac/Linux:
lsof -i :1234
The Issue: A downloaded model fails to initialize with a generic exit code, or the output is completely broken/unreadable.
The Cause: This is typically caused by a corrupted download, an unsupported architecture (like an un-merged draft architecture), or attempting to load a model with quantization settings your VRAM cannot handle.
The Fix: Delete the model from the "My Models" tab.
- Return to the Discover tab and re-download it ensure the download completes without interruption.
- If it still fails, ensure the model format is supported by your exact LM Studio version
e.g., GGUF, MLX.
- See my other guide
LM Studio MCP Server Configuration.md
Caution
This is provided "as-is" without any warranty of any kind. I am not responsible for any issues, data loss, or other problems that may arise from using this Info. (code-related or otherwise) Use it at your own risk.