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.
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
Step 4 already installed torch and torchvision from PyPI, because they are core dependencies of the backend. macOS gets an MPS-capable build; Linux and Windows get PyPI's default build, which is CPU-only on Windows. This is enough to run the app and test models. For a CUDA or ROCm build, reinstall from the matching wheel index; 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 --ws-max-size 67108864
--ws-max-size 67108864 gives the canvas WebSocket the 64 MB limit that cdui start and cdui dev set. Without it, uvicorn's own 16 MB limit applies, and the editor cannot run a graph larger than that.
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 # Windows: .\cdui.cmd dev
python scripts/dev.py dev
A cdui on PATH is the launcher the one-line installer writes. It always runs the directory that installer set up, not this clone.
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