Manual Installation

System Requirements Please check the system requirements page to make sure your hardware is capable of running the desired models.

Are you in the right place?

Local Installation Guide If you want to use Invoke locally, you should probably use the launcher instead.

Developer Installation Guide If you want to contribute to InvokeAI or run the app on the main branch, follow the developer installation guide instead.

Walkthrough

We’ll use uv to install python and create a virtual environment, then install the invokeai package. uv is a modern, very fast alternative to pip.

The following commands vary depending on the version of Invoke being installed and the system onto which it is being installed.

1. Install uv as described in its docs. We suggest using the standalone installer method.

   Run uv --version to confirm that uv is installed and working. After installation, you may need to restart your terminal to get access to uv.

2. Create a directory for your installation, typically in your home directory (e.g. ~/invokeai or $Home/invokeai):

   Windows

   mkdir $Home/invokeai
   cd $Home/invokeai

   Linux/MacOS

   mkdir ~/invokeai
   cd ~/invokeai

3. Create a virtual environment in that directory:

   uv venv --relocatable --prompt invoke --python 3.12 --python-preference only-managed .venv

   This command creates a portable virtual environment at .venv complete with a portable python 3.12. It doesn’t matter if your system has no python installed, or has a different version - uv will handle everything.

4. Activate the virtual environment:

   Windows

   .venv\Scripts\activate

   Linux/MacOS

   source .venv/bin/activate

5. Choose a version to install.

   View Releases

6. Determine the package specifier to use when installing. This is a performance optimization.

   • If you have an Nvidia 20xx series GPU or older, use invokeai[xformers].
   • If you have an Nvidia 30xx series GPU or newer, or do not have an Nvidia GPU, use invokeai.

7. Determine the torch backend to use for installation, if any. This is necessary to get the right version of torch installed. This is acheived by using UV’s built in torch support.

   Torch Backend Selection

   Pick a torch backend only when it applies to your system. In all other cases, do not use a torch backend.

   Windows
   Nvidia GPU

   Use:

   --torch-backend=cu128

   Other / no GPU

   Do not use a torch backend.

   Linux/MacOS
   Linux + Nvidia GPU

   Use:

   --torch-backend=cu128

   Linux + no GPU

   Use:

   --torch-backend=cpu

   Linux + AMD GPU

   Use:

   --torch-backend=rocm6.3

   All other cases

   Do not use a torch backend.

8. Install the invokeai package. Substitute the package specifier and version.

   No torch backend

   uv pip install <PACKAGE_SPECIFIER>==<VERSION> --python 3.12 --python-preference only-managed --force-reinstall

   With torch backend

   uv pip install <PACKAGE_SPECIFIER>==<VERSION> --python 3.12 --python-preference only-managed --torch-backend=<VERSION> --force-reinstall

9. Deactivate and reactivate your venv so that the invokeai-specific commands become available in the environment:

   Windows

   deactivate
   .venv\Scripts\activate

   Linux/MacOS

   deactivate && source .venv/bin/activate

10. Run the application, specifying the directory you created earlier as the root directory:

    Windows

    invokeai-web --root ~/invokeai

    Linux/MacOS

    invokeai-web --root $Home/invokeai

If you run Invoke on a headless server, you might want to install and run Invoke on the command line.

We do not plan to maintain scripts to do this moving forward, instead focusing our dev resources on the GUI launcher.

You can create your own scripts for this by copying the handful of commands in this guide. uv’s pip interface docs may be useful.