Running without Docker

For the adventurous. No safety net.

This is not the supported way to run picoDiffusion. The Docker setup is the recommended path. If something breaks, you get to keep both pieces.

Why Docker is better

One of the main reasons we use Docker is predictability. The container has the exact same Python version, the exact same libraries, the exact same CUDA setup every time. It just works.

Running natively means your system's Python version, your installed libraries, your CUDA drivers, and a dozen other things all need to line up. When they do not, debugging is complicated and frustrating. We cannot help you with that. Every system is different and the number of ways things can go wrong is large.

If you are here because you want MPS on a Mac, or because you do not want to install Docker, or because you enjoy this sort of thing — carry on. Just know what you are getting into. Besides, watching the build is kinda fun even though it takes a long time. Look mum, I'm a hacker!

What you need

git to clone the repository
curl for installing pyenv
An NVIDIA GPU with drivers installed — or Apple Silicon (M1, M2, M3, M4) for MPS acceleration

CPU-only is also possible, but it will be very slow. Several minutes per image. Your fans will hate you.

Need help with CUDA setup? If you do not have NVIDIA drivers installed yet, see our CUDA / NVIDIA Setup guide for step-by-step instructions for Ubuntu, Linux Mint, and Debian.

1. Install build tools

pyenv (step 3) builds Python from source, which means your system needs a C compiler and some development libraries. These are probably already installed, but if not:

sudo apt update
sudo apt install -y build-essential libssl-dev zlib1g-dev libbz2-dev \
  libreadline-dev libsqlite3-dev libncurses-dev libffi-dev liblzma-dev \
  curl git

sudo apt update refreshes your package list. The second command installs a C compiler (build-essential), development libraries that Python needs to build properly, plus curl and git. These go into your system but they are standard development tools that many other things use. sudo means it needs your password because it is installing system packages.

sudo apt update
sudo apt install -y build-essential libssl-dev zlib1g-dev libbz2-dev \
  libreadline-dev libsqlite3-dev libncurses-dev libffi-dev liblzma-dev \
  curl git

Same packages as Ubuntu/Mint. sudo apt update refreshes your package list. The second command installs a C compiler and development libraries that Python needs to build, plus curl and git.

xcode-select --install

This installs the Xcode Command Line Tools which include a C compiler and everything else pyenv needs. A window will pop up asking you to confirm. It takes a few minutes.

2. Get the code

Download the project files from GitHub:

git clone https://github.com/lacquerlabs/picodiffusion.git
cd picodiffusion

git clone downloads a copy of the project into a folder called picodiffusion. cd picodiffusion moves your terminal into that folder.

3. Install pyenv

Your system probably has Python already, but we do not want to touch it. We do not want to install gigabytes of PyTorch packages into your system Python. We want everything contained inside this project so when you are done, you delete the folder and your system is exactly as it was.

pyenv lets you install a separate Python that lives in your home directory. It does not need root and does not modify your system Python. It is also generally a good tool to have around if you ever work with Python again. We recommend keeping it even after you are done with picoDiffusion.

curl https://pyenv.run | bash

This downloads and runs the pyenv installer. curl fetches the script from the internet, and | bash runs it. It installs pyenv into ~/.pyenv in your home directory. Nothing goes into system directories.

After it finishes, it will tell you to add some lines to your shell config (~/.bashrc or ~/.zshrc). Do that, then restart your terminal or run source ~/.bashrc. This lets your terminal find the pyenv command.

4. Install Python 3.12

pyenv install 3.12
pyenv local 3.12

The first command downloads and builds Python 3.12. This takes a few minutes. The second command tells pyenv to use 3.12 in this project directory. It creates a .python-version file so pyenv remembers.

5. Create a virtual environment

A virtual environment is an isolated space for this project's packages. Nothing installed here touches anything outside this folder.

python -m venv venv
source venv/bin/activate

You need to run source venv/bin/activate every time you open a new terminal before running any of the commands below. If your terminal prompt starts with (venv), you are in the right place.

The whole point: pyenv installed Python 3.12 without touching your system. The venv keeps all packages inside this folder. When you are done with picoDiffusion, delete the project folder and optionally run pyenv uninstall 3.12. Your system is clean. No leftover packages, no modified system Python, nothing.

6. Install PyTorch

This is the tricky bit. The command depends on your hardware. This is also the big download. PyTorch with CUDA is about 2GB. It takes time. Patience.

For NVIDIA GPU (Linux)

pip install torch torchvision --index-url https://download.pytorch.org/whl/cu126

This installs PyTorch with CUDA 12.6 support, which covers everything from Pascal-era GPUs (GTX 1050 Ti, Quadro P2000) through the latest generation.

For Apple Silicon (MPS)

pip install torch torchvision

The default pip package includes MPS support out of the box. No special index URL needed.

For CPU only

pip install torch torchvision

Same command as Apple Silicon. It will work, just slowly. Very slowly.

7. Install dependencies

pip install -r app/requirements.txt

This installs the rest of the Python libraries picoDiffusion needs — the web server (FastAPI), the image generation library (diffusers), LoRA support (peft), and a few others. The -r flag tells pip to read the list from a file. This one is faster than PyTorch but still downloads a few hundred MB. Give it a minute.

8. Create model directories

The app needs folders to find your model files in. mkdir -p creates folders, and the -p means it creates any parent folders along the way.

mkdir -p cache/models/checkpoints cache/models/vae cache/models/loras cache/huggingface

Put your .safetensors checkpoint files in cache/models/checkpoints/, VAE files in cache/models/vae/, and LoRA files in cache/models/loras/. The cache/huggingface/ folder is where HuggingFace will download small config files on first run. See the Getting Started page for recommended checkpoints and VAEs to download.

9. Start the server

cd app moves into the application directory where the Python code lives. python main.py starts the web server.

cd app
python main.py

The first time you run this, it will take a moment to start up. When you see output saying it is running on port 8004, you are good to go. Press Ctrl+C to stop the server when you are done.

10. Open the UI

Open your web browser and go to http://localhost:8004. You should see the picoDiffusion interface, same as the Docker version.

If this worked, nice. If it did not, the Docker setup is always there. No judgement.

Cleanup

Done playing? Want your system back to how it was? Here is what to remove:

1. Delete the project folder

This removes the code, the virtual environment, all model files, and everything pip installed.

rm -rf picodiffusion

2. Remove the Python version from pyenv

pyenv uninstall 3.12

3. Remove pyenv itself (optional, not really recommended)

pyenv is a useful tool to have around. But if you really want it gone:

rm -rf ~/.pyenv

Then remove the lines pyenv added to your ~/.bashrc or ~/.zshrc.

4. Remove the HuggingFace cache

HuggingFace stores downloaded config files in your home directory. These are small (a few hundred MB at most) but if you want them gone:

rm -rf ~/.cache/huggingface

That is everything. Nothing else was installed outside of these locations.