Skip to content

Install

Install the app and open it in your browser. No account or payment is needed.

Check your machine

  • Mac: Apple silicon (M1 or newer) and macOS 14 Sonoma or newer.
  • Windows and Linux: an NVIDIA RTX 20-series or newer, with driver 580 or newer. There is no CPU fallback.
  • Disk: about 10 GB free for the app, plus room for the models you download.

The launcher checks this for you; the commands below are for checking by hand.

Open the Apple menu and choose About This Mac. It names the chip and the macOS version. An Intel Mac isn't supported.

In PowerShell, run nvidia-smi. The table names your card and shows the driver version at the top. To update an old driver, install the newest one from the NVIDIA driver page or with the NVIDIA App.

In a terminal, run nvidia-smi. The table names your card and shows the driver version at the top. To update an old driver, use your distribution's NVIDIA driver package or the NVIDIA driver page.

Models download into the Hugging Face cache; to move it to another drive, see Data folder.

Install with the launcher

The launcher installs the app and ffmpeg, starts the app and opens it in your browser, so you never open a terminal. It isn't signed yet, so your system warns you the first time you open it; the steps below get past it.

Download for macOS

  1. Open the downloaded .dmg, drag Z-Vision Generator into Applications, then open it from Applications. macOS says it can't verify the app.
  2. Open System Settings → Privacy & Security, scroll to the message about Z-Vision Generator and choose Open Anyway.

Download for Windows

  1. If your browser blocks the download, open its downloads list (Ctrl+J) and choose Keep.
  2. Run the downloaded .exe. At the Windows protected your PC warning, choose More info, then Run anyway.
  3. Follow the installer, then open Z-Vision Generator from the Start menu.

Download the AppImage Download the .deb Download the .rpm

  • AppImage, for most distributions: in its Properties, tick Allow executing file as program, then open it.
  • .deb (Ubuntu, Debian) or .rpm (Fedora): open it with your software installer, then open Z-Vision Generator from your applications menu.

Choose Install in the launcher window. When it is done, your browser opens at the app, which offers an image model picked for your machine; Your first image takes it from there. Next time, open the launcher to start the app; Quit stops it. If it can't install, see Troubleshooting.

Update, Repair, Uninstall… and Get beta versions are in the launcher window (the last three in the ⋯ menu) and keep your data and models. Use Uninstall… before you delete the launcher; if you already did, see The launcher's folder. The launcher doesn't update itself: quit it and download it again from Install with the launcher; on macOS, choose Open Anyway again.

Install from a terminal

The steps below install the same app from a terminal; use them for the ziv commands, for phones, tablets and other computers, or to keep the data folder or models on another drive on macOS or Linux, and skip this section if you used the launcher.

1. Open a terminal

The rest of the steps are commands.

Open Terminal: press Cmd+Space, type Terminal and press Enter.

Open PowerShell: press the Start key, type PowerShell and press Enter.

Open your terminal application.

2. Get uv

uv installs the app and brings its own Python, so you need nothing else first.

curl -LsSf https://astral.sh/uv/install.sh | sh
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
curl -LsSf https://astral.sh/uv/install.sh | sh

Close the terminal and open a new one, so that it finds uv.

3. Install

uv tool install z-vision-generator
uv tool install z-vision-generator --torch-backend cu132

PyPI's PyTorch for Windows has no CUDA, so an install from PyPI alone ends with "… cannot run: the installed PyTorch has no CUDA" even on an NVIDIA card. --torch-backend cu132 takes PyTorch, and only PyTorch, from PyTorch's CUDA index. It needs uv 0.11.29 or newer (uv self update updates an older uv), and uv prints a warning that the option is experimental, which is expected.

uv tool install z-vision-generator

4. Get ffmpeg

ffmpeg is a free tool that video and audio need to write their files.

brew install ffmpeg
winget install --id Gyan.FFmpeg --exact

Open a new PowerShell window afterwards.

sudo apt install ffmpeg

5. Start it

ziv ui

Your browser opens at the address the terminal prints, usually http://127.0.0.1:8080/. Keep the terminal open while you use the app; Ctrl+C in it stops the app. To use it again tomorrow, run ziv ui again.

The first time, the app offers to download an image model picked for your machine. Your first image takes it from there.

To use it from a phone or tablet, see Phones, tablets and other computers.

If it doesn't start, see Troubleshooting.

Update

uv tool upgrade z-vision-generator
uv tool install --upgrade z-vision-generator --torch-backend cu132

Use this command, not uv tool upgrade. uv tool upgrade can't take --torch-backend, so on Windows it would bring back a PyTorch without CUDA.

uv tool upgrade z-vision-generator

If you installed with the launcher, use Update in its window instead.

Your LoRAs, settings and outputs live in the data folder, and downloaded models in the Hugging Face cache, not in the install, so they survive an update.

Repair the install

If the app reports a missing or outdated package, reinstall it. Your data folder and downloaded models stay as they are.

uv tool install --reinstall z-vision-generator
uv tool install --reinstall z-vision-generator --torch-backend cu132

Keep --torch-backend cu132. Without it, uv takes PyTorch from PyPI, which has no CUDA on Windows.

uv tool install --reinstall z-vision-generator

In a checkout, run uv sync instead. If you installed with the launcher, use Repair in its window instead.

Uninstall

uv tool uninstall z-vision-generator

If you installed with the launcher, use Uninstall… in its window instead; if you already deleted the launcher, see The launcher's folder.

The data folder stays, with your LoRAs, outputs and converted models, and so do the downloaded models in the Hugging Face cache. Delete them to free the space; both locations are in Data folder.

Other ways to install

The latest code, or a checkout

The latest code from the repository:

uv tool install git+https://github.com/knuthelge/ZVisionGenerator.git

On Windows, add --torch-backend cu132, as in step 3.

A checkout for working on the code: see Developer.

git clone https://github.com/knuthelge/ZVisionGenerator && cd ZVisionGenerator
uv sync
uv run ziv ui