Skip to main content

Dev Install

Manual setup using uv and pnpm — works on Windows, macOS, and Linux. Use this for development or contributing, when you want hot reload on both the backend and frontend.

tip

If you only want to run CodefyUI, use the one-line installer instead — it needs no Node.js or pnpm.

1. Clone the repository​

git clone https://github.com/CodefyUI/CodefyUI.git
cd CodefyUI

2. Install uv​

uv --version

If not installed:

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or via pip
pip install uv

3. Install pnpm + Node.js​

pnpm --version

If not installed:

# Windows (PowerShell)
iwr https://get.pnpm.io/install.ps1 -useb | iex

# macOS / Linux
curl -fsSL https://get.pnpm.io/install.sh | sh -

Then let pnpm install a Node.js runtime (Node 24+ is recommended):

pnpm env use --global lts

Restart your terminal so PATH updates take effect, then verify:

node -v

4. Backend setup​

cd backend

# Create a virtual environment with Python 3.10+
uv venv --python 3.11

# Activate it
.venv\Scripts\activate       # Windows
source .venv/bin/activate    # macOS / Linux

# Install core dependencies + test tools
uv pip install -e ".[dev]"

5. Install PyTorch​

The default install works on every platform:

uv pip install torch torchvision

macOS gets an MPS-capable build; Linux/Windows get the default PyPI build. This is enough to run the app and test models. For a specific GPU configuration, see GPU & Device Setup.

6. Start backend + frontend​

Developer mode (HMR)​

Backend (terminal 1):

cd backend
.venv\Scripts\activate       # Windows
source .venv/bin/activate    # macOS / Linux

uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

If you change the port or bind address, set CODEFYUI_PORT and CODEFYUI_HOST to the same values. The server derives its Host allowlist from these variables rather than from the listening socket. When the port differs, every request returns 421; when the bind address differs, only requests from other machines do, because loopback names are always allowed. cdui start --project sets CODEFYUI_PROJECT_DIR=<absolute dir>. A uvicorn process started directly with this command stores its session token and other user data in the platform data directory: %LOCALAPPDATA%\codefyui, ~/.local/share/codefyui, or ~/Library/Application Support/codefyui. It does not use .codefyui_dev/. See Project Directories.

Frontend (terminal 2):

cd frontend
pnpm install
pnpm dev

Open http://localhost:5173. The Vite dev server proxies API/WS to the backend on :8000.

Or start both at once from the project root:

cdui dev                 # if ~/.local/bin is on PATH
./cdui dev               # from the project root
python scripts/dev.py dev

Running tests​

cdui test                    # backend (pytest) + frontend (vitest); --backend / --frontend narrow it

cdui test requires the [dev] extra installed in step 4. When using the launcher, install it with cdui install --dev. With the one-line installer, set CODEFYUI_FORCE_BUILD=1 CODEFYUI_DEV=1. To run the backend suite directly:

cd backend
.venv\Scripts\activate       # or source .venv/bin/activate
pytest tests/ -v