ACE-Step 1.5 Installation Guide

Language / 语言 / 言語: English | 中文 | 日本語

Table of Contents

• Requirements
• Quick Start (All Platforms)
• Launch Scripts
• Windows Portable Package
• macOS Portable Package
• AMD / ROCm GPUs
• Intel GPUs
• CPU-Only Mode
• Linux Notes
• Environment Variables (.env)
• Command Line Options
• Model Download
• Which Model Should I Choose?
• Development

Requirements

Quick Start (All Platforms)

1. Install uv (Package Manager)

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

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

2. Clone & Install

git clone https://github.com/ACE-Step/ACE-Step-1.5.git
cd ACE-Step-1.5
uv sync

3. Launch

Gradio Web UI (Recommended):

uv run acestep

REST API Server:

uv run acestep-api

Using Python directly (Conda / venv / system Python):

# Activate your environment first, then:
python acestep/acestep_v15_pipeline.py          # Gradio UI
python acestep/api_server.py                     # REST API

Models are downloaded automatically on first run. Open http://localhost:7860 (Gradio) or http://localhost:8001 (API).

🚀 Launch Scripts

Ready-to-use launch scripts for all platforms. These scripts handle environment detection, dependency installation, and application startup automatically. All scripts check for updates on startup by default (configurable).

Available Scripts

Windows

# Launch Gradio Web UI (NVIDIA CUDA)
start_gradio_ui.bat

# Launch REST API Server (NVIDIA CUDA)
start_api_server.bat

# Launch Gradio Web UI (AMD ROCm)
start_gradio_ui_rocm.bat

# Launch REST API Server (AMD ROCm)
start_api_server_rocm.bat

ROCm users: The ROCm scripts (start_gradio_ui_rocm.bat, start_api_server_rocm.bat) auto-set HSA_OVERRIDE_GFX_VERSION, ACESTEP_LM_BACKEND=pt, MIOPEN_FIND_MODE=FAST and other ROCm-specific environment variables. They use a separate venv_rocm virtual environment to avoid CUDA/ROCm wheel conflicts.

Linux

# Make executable (first time only)
chmod +x start_gradio_ui.sh start_api_server.sh

# Launch Gradio Web UI
./start_gradio_ui.sh

# Launch REST API Server
./start_api_server.sh

Note: Git must be installed via your system package manager (sudo apt install git, sudo yum install git, sudo pacman -S git).

macOS (Apple Silicon / MLX)

macOS scripts use the MLX backend for native Apple Silicon acceleration (M1/M2/M3/M4).

# Make executable (first time only)
chmod +x start_gradio_ui_macos.sh start_api_server_macos.sh

# Launch Gradio Web UI with MLX backend
./start_gradio_ui_macos.sh

# Launch REST API Server with MLX backend
./start_api_server_macos.sh

The macOS scripts automatically set ACESTEP_LM_BACKEND=mlx and --backend mlx for native Apple Silicon acceleration, and fall back to PyTorch backend on non-arm64 machines.

Note: Install git via xcode-select --install or brew install git.

Script Features

• Startup update check (enabled by default, configurable)
• Auto environment detection (portable Python or uv)
• Auto install uv if needed
• Configurable download source (HuggingFace/ModelScope)
• Customizable models and parameters

How to Modify Configuration

All configurable options are defined as variables at the top of each script. To customize, open the script with a text editor and modify the variable values.

Example: Change UI language to Chinese and use the 1.7B LM model

set LANGUAGE=en
set LM_MODEL_PATH=--lm_model_path acestep-5Hz-lm-0.6B

set LANGUAGE=zh
set LM_MODEL_PATH=--lm_model_path acestep-5Hz-lm-1.7B

LANGUAGE="en"
LM_MODEL_PATH="--lm_model_path acestep-5Hz-lm-0.6B"

LANGUAGE="zh"
LM_MODEL_PATH="--lm_model_path acestep-5Hz-lm-1.7B"

Example: Disable startup update check

REM set CHECK_UPDATE=true
set CHECK_UPDATE=false

# CHECK_UPDATE="true"
CHECK_UPDATE="false"

Example: Enable a commented-out option — remove the comment prefix (REM for .bat, # for .sh):

REM set SHARE=--share

set SHARE=--share

# SHARE="--share"

SHARE="--share"

Common configurable options:

Update & Maintenance Tools

Update workflow:

# Windows                          # Linux / macOS
check_update.bat                    ./check_update.sh
merge_config.bat                    ./merge_config.sh

🪟 Windows Portable Package

For Windows users, we provide a portable package with pre-installed dependencies:

1. Download and extract: ACE-Step-1.5.7z
2. The package includes python_embedded with all dependencies pre-installed
3. Requirements: CUDA 12.8

Quick Start Scripts

Both scripts support auto environment detection, auto uv install, configurable download source, optional Git update check, and customizable models/parameters.

Configuration

start_gradio_ui.bat:

REM UI language (en, zh, he, ja)
set LANGUAGE=zh

REM Download source (auto, huggingface, modelscope)
set DOWNLOAD_SOURCE=--download-source modelscope

REM Git update check (true/false)
set CHECK_UPDATE=true

REM Model configuration
set CONFIG_PATH=--config_path acestep-v15-turbo
set LM_MODEL_PATH=--lm_model_path acestep-5Hz-lm-1.7B

start_api_server.bat:

REM LLM initialization via environment variable
REM set ACESTEP_INIT_LLM=true   # Force enable LLM
REM set ACESTEP_INIT_LLM=false  # Force disable LLM (DiT-only mode)

Update & Maintenance

Update workflow:

check_update.bat          # 1. Check for updates (requires PortableGit/)
merge_config.bat          # 2. Merge settings back if conflicts occur

Portable Git Support

Place a PortableGit/ folder in your package to enable auto-updates:

set CHECK_UPDATE=true     # in start_gradio_ui.bat or start_api_server.bat

Features: 10s timeout protection, smart conflict detection & backup, automatic rollback on failure, directory structure preserved in backups.

Environment Detection Priority

1. python_embedded\python.exe (if exists)
2. uv run acestep (if uv is installed)
3. Auto-install uv via winget or PowerShell

🍎 macOS Portable Package

For macOS users (Apple Silicon), we provide a portable package with pre-installed dependencies:

1. Download and extract: ACE-Step-1.5.zip
2. The package includes all dependencies pre-installed with MLX backend support
3. Requirements: Apple Silicon (M1/M2/M3/M4) with macOS

Quick Start Scripts

# Make executable (first time only)
chmod +x start_gradio_ui_macos.sh start_api_server_macos.sh

# Launch Gradio Web UI with MLX backend
./start_gradio_ui_macos.sh

# Launch REST API Server with MLX backend
./start_api_server_macos.sh

The macOS scripts automatically set ACESTEP_LM_BACKEND=mlx and --backend mlx for native Apple Silicon acceleration.

Configuration

Configurable options are defined as variables at the top of each script. Open the script with a text editor to customize:

# UI language (en, zh, he, ja)
LANGUAGE="en"

# Download source (auto, huggingface, modelscope)
DOWNLOAD_SOURCE="--download-source auto"

# Git update check (true/false)
CHECK_UPDATE="true"

# Model configuration
CONFIG_PATH="--config_path acestep-v15-turbo"
LM_MODEL_PATH="--lm_model_path acestep-5Hz-lm-1.7B"

AMD / ROCm GPUs

⚠️ uv run acestep installs CUDA PyTorch wheels and may overwrite an existing ROCm setup.

Windows - ROCm 7.2 (Python 3.12 Required)

Important: AMD ROCm 7.2 on Windows requires Python 3.12 (AMD officially provides Python 3.12 wheels only).

# 1. Ensure you have Python 3.12 installed
python --version  # Should show Python 3.12.x

# 2. Create and activate a virtual environment
python -m venv venv_rocm
venv_rocm\Scripts\activate

# 3. Follow the installation steps in requirements-rocm.txt
# This installs ROCm SDK and PyTorch wheels from AMD's repository

# 4. Install dependencies
pip install -r requirements-rocm.txt

# 5. Launch with the ROCm-specific launcher
start_gradio_ui_rocm.bat
# OR
start_api_server_rocm.bat

See requirements-rocm.txt for detailed ROCm 7.2 installation steps.

Linux - ROCm 6.0+ (Python 3.11 or 3.12)

# 1. Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate

# 2. Install ROCm-compatible PyTorch
pip install torch --index-url https://download.pytorch.org/whl/rocm6.0

# 3. Install ACE-Step
pip install -e .

# 4. Start the service
python -m acestep.acestep_v15_pipeline --port 7680

Note: torchcodec is not available for AMD ROCm GPUs due to CUDA-specific dependencies. ACE-Step automatically uses soundfile as a fallback for audio I/O, which provides full functionality on ROCm platforms.

GPU Detection Troubleshooting

If you see "No GPU detected, running on CPU" with an AMD GPU:

1. Run the diagnostic tool: python scripts/check_gpu.py
2. For RDNA3 GPUs, set HSA_OVERRIDE_GFX_VERSION:

3. On Windows, use start_gradio_ui_rocm.bat / start_api_server_rocm.bat which set required environment variables automatically.
4. Verify ROCm installation: rocm-smi should list your GPU.

Linux (cachy-os / RDNA4)

See ACE-Step1.5-Rocm-Manual-Linux.md for a detailed ROCm manual tested with RDNA4 on cachy-os.

Intel GPUs

Note: LLM inference speed may decrease when generating audio longer than 2 minutes. Intel discrete GPUs are expected to work but not yet tested.

Audio I/O: torchcodec is not available for Intel XPU GPUs. ACE-Step automatically uses soundfile as a fallback for audio I/O, which provides full functionality on Intel platforms.

CPU-Only Mode

ACE-Step can run on CPU for inference only, but performance will be significantly slower.

• Training (including LoRA) on CPU is not recommended.
• For low-VRAM systems, DiT-only mode (LLM disabled) is supported.

If you do not have a GPU, consider:

• Using cloud GPU providers
• Running inference-only workflows
• Using DiT-only mode with ACESTEP_INIT_LLM=false

Linux Notes

Python 3.11 Pre-Release Issue

Some Linux distributions (including Ubuntu) ship Python 3.11.0rc1, which is a pre-release build. This can cause segmentation faults with the vLLM backend.

Recommendation: Use a stable Python release (≥ 3.11.12). On Ubuntu, install via the deadsnakes PPA.

If upgrading Python is not possible, use the PyTorch backend:

uv run acestep --backend pt

Environment Variables (.env)

The .env file provides a centralized way to configure ACE-Step. Settings in .env are:

• Used by Python scripts (CLI, API server, Gradio UI)
• Now also used by launcher scripts (start_gradio_ui.bat, start_gradio_ui.sh, etc.)
• Preserved across repository updates (unlike hardcoded values in launcher scripts)

cp .env.example .env   # Copy and edit

Benefits of Using .env

✅ Survives Updates: Your custom model paths and settings won't be overwritten when you update ACE-Step
✅ Cross-Platform: Same configuration works on Windows, Linux, and macOS
✅ Version Control Safe: .env is in .gitignore, so your personal settings stay private

Key Variables

LLM Initialization (ACESTEP_INIT_LLM)

Processing flow: GPU Detection → ACESTEP_INIT_LLM Override → Model Loading

Example .env for different scenarios:

# Auto mode (recommended)
ACESTEP_INIT_LLM=auto

# Force enable on low VRAM GPU
ACESTEP_INIT_LLM=true
ACESTEP_LM_MODEL_PATH=acestep-5Hz-lm-0.6B

# Force disable LLM for faster generation
ACESTEP_INIT_LLM=false

Command Line Options

Gradio UI (acestep)

Examples:

# Public access with Chinese UI
uv run acestep --server-name 0.0.0.0 --share --language zh

# Pre-initialize models on startup
uv run acestep --init_service true --config_path acestep-v15-turbo

# Set default batch size to 4
uv run acestep --batch_size 4

# Enable API endpoints with authentication
uv run acestep --enable-api --api-key sk-your-secret-key --port 8001

# Use ModelScope as download source
uv run acestep --download-source modelscope

📥 Model Download

Models are automatically downloaded from HuggingFace or ModelScope on first run.

CLI Download

uv run acestep-download                              # Download main model
uv run acestep-download --all                         # Download all models
uv run acestep-download --download-source modelscope  # From ModelScope
uv run acestep-download --model acestep-v15-sft       # Specific model
uv run acestep-download --list                        # List all available

Or with Python directly:

python -m acestep.model_downloader                    # Download main model
python -m acestep.model_downloader --all              # Download all models

Manual Download (huggingface-cli)

# Main model (vae, Qwen3-Embedding-0.6B, acestep-v15-turbo, acestep-5Hz-lm-1.7B)
huggingface-cli download ACE-Step/Ace-Step1.5 --local-dir ./checkpoints

# Optional LM models
huggingface-cli download ACE-Step/acestep-5Hz-lm-0.6B --local-dir ./checkpoints/acestep-5Hz-lm-0.6B
huggingface-cli download ACE-Step/acestep-5Hz-lm-4B --local-dir ./checkpoints/acestep-5Hz-lm-4B

# XL (4B) DiT models - requires ≥12GB VRAM (with offload)
huggingface-cli download ACE-Step/acestep-v15-xl-base --local-dir ./checkpoints/acestep-v15-xl-base
huggingface-cli download ACE-Step/acestep-v15-xl-sft --local-dir ./checkpoints/acestep-v15-xl-sft
huggingface-cli download ACE-Step/acestep-v15-xl-turbo --local-dir ./checkpoints/acestep-v15-xl-turbo

Shared Model Directory

If you have multiple ACE-Step installations (e.g., trainers, different versions), you can share a single model directory to avoid duplicate downloads and save disk space:

# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
export ACESTEP_CHECKPOINTS_DIR=~/ace-step-models

All installations will then use the same model files. You can also set this in your .env file.

Available Models

💡 Which Model Should I Choose?

ACE-Step automatically adapts to your GPU's VRAM. The UI pre-configures all settings (LM model, backend, offloading, quantization) based on your detected GPU tier:

📖 For detailed GPU compatibility information (tier table, duration limits, batch sizes, adaptive UI defaults, memory optimization), see GPU Compatibility Guide.

Development

# Add dependencies
uv add package-name
uv add --dev package-name

# Update all dependencies
uv sync --upgrade