Skip to content
Get packs

Guide · Open source

How to use ACE-Step-1.5: install, run locally and generate music

Updated · written with AI from the project's own documentation and checked against our catalogue data

ACE-Step-1.5 is an open-source music generation model, released under the MIT licence, that you can run on your own computer instead of a cloud service. You describe a song in text and it can produce audio including lyrics and structure. This guide walks through installing it with uv, launching the Gradio interface, and choosing a model that fits your hardware.

ACE-Stepace-step/ACE-Step-1.5 · ★ 14.3k · MIT

Quick start

  1. 1Install uv. Run the uv install script for macOS or Linux, or the PowerShell command for Windows.
  2. 2Clone the repository. Run git clone on https://github.com/ACE-Step/ACE-Step-1.5.git and change into the ACE-Step-1.5 folder.
  3. 3Install dependencies. Run uv sync inside the project folder to install the Python dependencies.
  4. 4Launch the Gradio UI. Run uv run acestep and wait for the model files to download on the first run.
  5. 5Open the interface. Go to http://localhost:7860 in your browser to start generating.
  6. 6Pick a model for your VRAM. Check the README's VRAM table and choose a DiT and LM pair that fits your GPU.

What ACE-Step-1.5 needs before you install

The README lists Python 3.11-3.12 and the uv Python package manager as prerequisites. A CUDA GPU is recommended, but the project also lists Apple Mac (MPS), AMD (ROCm), Intel XPU and CPU as supported paths.

Setup is not a one-click process. If you have no capable GPU or do not want to set up a Python environment, the README points to the hosted site at acemusic.ai instead.

  • Python 3.11 or 3.12
  • uv (Python package manager)
  • CUDA GPU recommended; MPS, ROCm, Intel XPU or CPU also supported
  • ROCm on Windows requires Python 3.12, per the README

Install ACE-Step-1.5 with uv

Install uv, clone the repository, then install the dependencies from inside the project folder. The README gives these commands for macOS and Linux; Windows uses a PowerShell command listed in the same Quick Start section.

Model files download automatically the first time you launch the app, according to the README's Quick Start comment.

curl -LsSf https://astral.sh/uv/install.sh | sh git clone https://github.com/ACE-Step/ACE-Step-1.5.git cd ACE-Step-1.5 uv sync

Launch the Gradio UI and open it in your browser

Run the Gradio interface with uv. The README says the UI opens at http://localhost:7860. From the same project, the README also lists a REST API server command, which serves on port 8001.

If you want the REST API instead of the visual interface, the README gives uv run acestep-api as the command.

  • Gradio UI: http://localhost:7860
  • REST API: http://localhost:8001
uv run acestep # or for the REST API server: uv run acestep-api

Choose a model that matches your GPU VRAM

The README includes a table that maps GPU memory to a recommended DiT model and language model (LM). Smaller GPUs use the 2B turbo DiT with the 0.6B LM or no LM at all. Larger cards can use the XL models and the 4B LM.

The README states the model runs locally with less than 4GB of VRAM, but the XL models need more: it lists at least 12GB with offload and at least 20GB recommended.

  • 6GB or less: 2B turbo, no LM (DiT only), INT8 quantization and full CPU offload
  • 6-8GB: 2B turbo with acestep-5Hz-lm-0.6B using the pt backend
  • 8-16GB: 2B turbo/sft with the 0.6B or 1.7B LM using the vllm backend
  • 20-24GB: XL turbo/sft with acestep-5Hz-lm-1.7B
  • 24GB or more: XL sft with acestep-5Hz-lm-4B

Use the main features: generate, cover, repaint and separate

The README's feature table lists the main controls. Simple Mode generates full songs from a plain description. Metadata Control sets duration, BPM, key/scale and time signature. Lyrics prompts control structure and style, and the project lists support for 50+ languages.

Editing tools include Cover Generation (create covers from existing audio), Repaint & Edit (regenerate selected parts of audio), Track Separation (split audio into stems) and Vocal2BGM (generate accompaniment for a vocal track).

  • Simple Mode: full song from a description
  • Metadata Control: duration, BPM, key/scale, time signature
  • Cover Generation and Repaint & Edit
  • Track Separation into stems
  • Vocal2BGM: accompaniment for a vocal track
  • LRC Generation: lyric timestamps for generated music

Know the limits and where to get help

The README states that generation duration runs from 10 seconds to 10 minutes and that batch generation makes up to 8 songs at once. Full installation options for AMD/ROCm, Intel GPU, CPU, environment variables and command-line options are in the project's INSTALL guide.

The README does not say anything about commercial rights to outputs beyond the MIT licence of the code, so check that yourself before using generated music commercially.

  • Duration: 10 seconds to 10 minutes
  • Batch: up to 8 songs simultaneously
  • Full install guide: docs/en/INSTALL.md in the repository

What people use it for

  • Sketching song ideas and rough arrangements for a music project
  • Generating background music or accompaniment for a vocal track (Vocal2BGM)
  • Creating covers of existing audio or repainting selected sections
  • Separating a mixed track into individual stems
  • Building music features into an app through the REST API

Frequently asked questions

Is ACE-Step-1.5 free?

The code is released under the MIT licence, as listed in the project details. The README also promotes the hosted acemusic.ai site as 100% free. The README does not address rights to the generated output beyond the code licence.

What hardware do I need to run ACE-Step-1.5?

The README recommends a CUDA GPU and lists Python 3.11-3.12 and uv as prerequisites. It also supports Apple Mac (MPS), AMD (ROCm), Intel XPU and CPU. The model runs with less than 4GB of VRAM, while the XL models need at least 12GB with offload.

How do I install ACE-Step-1.5?

Install uv, clone the GitHub repository, run uv sync inside the folder, then run uv run acestep to launch the Gradio UI. The README says models download automatically on first run.

Can ACE-Step-1.5 run on a Mac or on AMD?

Yes, according to the README. It lists MPS for Apple Mac and ROCm for AMD as supported backends. It also notes that ROCm on Windows requires Python 3.12.

How does ACE-Step-1.5 compare to Suno or Udio?

Suno and Udio are commercial and not open source. ACE-Step-1.5 is open source and runs locally. The README claims its quality is beyond most commercial music models, but it gives no independent comparison, so test it on your own material.

Why won't ACE-Step-1.5 start or run out of memory?

The README's VRAM table suggests using a smaller DiT model, a smaller LM, or no LM on low-memory cards. It also mentions INT8 quantization and CPU offload for limited GPUs. The full INSTALL guide covers environment variables and command-line options.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

ACE-Step-1.5 suits musicians, producers and developers who want a free, local tool for song sketches, accompaniment and experiments, and who have a reasonably capable GPU or are comfortable with a Python setup. If you want a polished app with no installation, use the hosted acemusic.ai site or a commercial service instead, and if you need clear commercial rights to outputs, check the terms before relying on it.

Install options & downloads