diff --git a/README.md b/README.md index 62b4bb58e5..d39c1004e6 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@
-![project logo](https://github.com/mauwii/InvokeAI/raw/main/docs/assets/invoke_ai_banner.png) +![project logo](https://github.com/invoke-ai/InvokeAI/raw/main/docs/assets/invoke_ai_banner.png) # InvokeAI: A Stable Diffusion Toolkit @@ -41,38 +41,136 @@ requests. Be sure to use the provided templates. They will help us diagnose issu
-![canvas preview](https://github.com/mauwii/InvokeAI/raw/main/docs/assets/canvas_preview.png) +![canvas preview](https://github.com/invoke-ai/InvokeAI/raw/main/docs/assets/canvas_preview.png)
-# Getting Started with InvokeAI +## Table of Contents + +1. [Quick Start](#getting-started-with-invokeai) +2. [Installation](#detailed-installation-instructions) +3. [Hardware Requirements](#hardware-requirements) +4. [Features](#features) +5. [Latest Changes](#latest-changes) +6. [Troubleshooting](#troubleshooting) +7. [Contributing](#contributing) +8. [Contributors](#contributors) +9. [Support](#support) +10. [Further Reading](#further-reading) + +## Getting Started with InvokeAI For full installation and upgrade instructions, please see: [InvokeAI Installation Overview](https://invoke-ai.github.io/InvokeAI/installation/) +### Automatic Installer (suggested for 1st time users) + 1. Go to the bottom of the [Latest Release Page](https://github.com/invoke-ai/InvokeAI/releases/latest) + 2. Download the .zip file for your OS (Windows/macOS/Linux). + 3. Unzip the file. -4. If you are on Windows, double-click on the `install.bat` script. On macOS, open a Terminal window, drag the file `install.sh` from Finder into the Terminal, and press return. On Linux, run `install.sh`. -5. Wait a while, until it is done. -6. The folder where you ran the installer from will now be filled with lots of files. If you are on Windows, double-click on the `invoke.bat` file. On macOS, open a Terminal window, drag `invoke.sh` from the folder into the Terminal, and press return. On Linux, run `invoke.sh` -7. Press 2 to open the "browser-based UI", press enter/return, wait a minute or two for Stable Diffusion to start up, then open your browser and go to http://localhost:9090. -8. Type `banana sushi` in the box on the top left and click `Invoke` +4. If you are on Windows, double-click on the `install.bat` script. On +macOS, open a Terminal window, drag the file `install.sh` from Finder +into the Terminal, and press return. On Linux, run `install.sh`. -## Table of Contents +5. You'll be asked to confirm the location of the folder in which +to install InvokeAI and its image generation model files. Pick a +location with at least 15 GB of free memory. More if you plan on +installing lots of models. -1. [Installation](#installation) -2. [Hardware Requirements](#hardware-requirements) -3. [Features](#features) -4. [Latest Changes](#latest-changes) -5. [Troubleshooting](#troubleshooting) -6. [Contributing](#contributing) -7. [Contributors](#contributors) -8. [Support](#support) -9. [Further Reading](#further-reading) +6. Wait while the installer does its thing. After installing the software, +the installer will launch a script that lets you configure InvokeAI and +select a set of starting image generaiton models. -## Installation +7. Find the folder that InvokeAI was installed into (it is not the +same as the unpacked zip file directory!) The default location of this +folder (if you didn't change it in step 5) is `~/invokeai` on +Linux/Mac systems, and `C:\Users\YourName\invokeai` on Windows. This directory will contain launcher scripts named `invoke.sh` and `invoke.bat`. + +8. On Windows systems, double-click on the `invoke.bat` file. On +macOS, open a Terminal window, drag `invoke.sh` from the folder into +the Terminal, and press return. On Linux, run `invoke.sh` + +9. Press 2 to open the "browser-based UI", press enter/return, wait a +minute or two for Stable Diffusion to start up, then open your browser +and go to http://localhost:9090. + +10. Type `banana sushi` in the box on the top left and click `Invoke` + +### Command-Line Installation (for users familiar with Terminals) + +You must have Python 3.9 or 3.10 installed on your machine. Earlier or later versions are +not supported. + +1. Open a command-line window on your machine. The PowerShell is recommended for Windows. +2. Create a directory to install InvokeAI into. You'll need at least 15 GB of free space: + + ```terminal + mkdir invokeai + ```` + +3. Create a virtual environment named `.venv` inside this directory and activate it: + + ```terminal + cd invokeai + python -m venv .venv --prompt InvokeAI + ``` + +4. Activate the virtual environment (do it every time you run InvokeAI) + + _For Linux/Mac users:_ + + ```sh + source .venv/bin/activate + ``` + + _For Windows users:_ + + ```ps + .venv\Scripts\activate + ``` + +5. Install the InvokeAI module and its dependencies. Choose the command suited for your platform & GPU. + + _For Windows/Linux with an NVIDIA GPU:_ + + ```terminal + pip install InvokeAI[xformers] --use-pep517 --extra-index-url https://download.pytorch.org/whl/cu117 + ``` + + _For Linux with an AMD GPU:_ + + ```sh + pip install InvokeAI --use-pep517 --extra-index-url https://download.pytorch.org/whl/rocm5.2 + ``` + + _For Macintoshes, either Intel or M1/M2:_ + + ```sh + pip install InvokeAI --use-pep517 + ``` + +6. Configure InvokeAI and install a starting set of image generation models (you only need to do this once): + + ```terminal + invokeai-configure + ``` + +7. Launch the web server (do it every time you run InvokeAI): + + ```terminal + invokeai --web + ``` + +8. Point your browser to http://localhost:9090 to bring up the web interface. +9. Type `banana sushi` in the box on the top left and click `Invoke`. + +Be sure to activate the virtual environment each time before re-launching InvokeAI, +using `source .venv/bin/activate` or `.venv\Scripts\activate`. + +### Detailed Installation Instructions This fork is supported across Linux, Windows and Macintosh. Linux users can use either an Nvidia-based card (with CUDA support) or an @@ -80,13 +178,13 @@ AMD card (using the ROCm driver). For full installation and upgrade instructions, please see: [InvokeAI Installation Overview](https://invoke-ai.github.io/InvokeAI/installation/INSTALL_SOURCE/) -### Hardware Requirements +## Hardware Requirements InvokeAI is supported across Linux, Windows and macOS. Linux users can use either an Nvidia-based card (with CUDA support) or an AMD card (using the ROCm driver). -#### System +### System You will need one of the following: @@ -98,11 +196,11 @@ We do not recommend the GTX 1650 or 1660 series video cards. They are unable to run in half-precision mode and do not have sufficient VRAM to render 512x512 images. -#### Memory +### Memory - At least 12 GB Main Memory RAM. -#### Disk +### Disk - At least 12 GB of free disk space for the machine learning model, Python, and all its dependencies. @@ -152,7 +250,7 @@ Notes](https://github.com/invoke-ai/InvokeAI/releases) and the Please check out our **[Q&A](https://invoke-ai.github.io/InvokeAI/help/TROUBLESHOOT/#faq)** to get solutions for common installation problems and other issues. -# Contributing +## Contributing Anyone who wishes to contribute to this project, whether documentation, features, bug fixes, code cleanup, testing, or code reviews, is very much encouraged to do so. diff --git a/docs/installation/020_INSTALL_MANUAL.md b/docs/installation/020_INSTALL_MANUAL.md index 57e508fef9..cf9063729f 100644 --- a/docs/installation/020_INSTALL_MANUAL.md +++ b/docs/installation/020_INSTALL_MANUAL.md @@ -30,25 +30,35 @@ Installation](010_INSTALL_AUTOMATED.md), and in many cases will already be installed (if, for example, you have used your system for gaming): -* **Python** version 3.9 or 3.10 (3.11 is not recommended). +* **Python** -* **CUDA Tools** For those with _NVidia GPUs_, you will need to - install the [CUDA toolkit and optionally the XFormers library](070_INSTALL_XFORMERS.md). + version 3.9 or 3.10 (3.11 is not recommended). -* **ROCm Tools** For _Linux users with AMD GPUs_, you will need - to install the [ROCm toolkit](./030_INSTALL_CUDA_AND_ROCM.md). Note that - InvokeAI does not support AMD GPUs on Windows systems due to - lack of a Windows ROCm library. +* **CUDA Tools** -* **Visual C++ Libraries** _Windows users_ must install the free - [Visual C++ libraries from Microsoft](https://learn.microsoft.com/en-US/cpp/windows/latest-supported-vc-redist?view=msvc-170) + For those with _NVidia GPUs_, you will need to + install the [CUDA toolkit and optionally the XFormers library](070_INSTALL_XFORMERS.md). -* **The Xcode command line tools** for _Macintosh users_. Instructions are - available at [Free Code Camp](https://www.freecodecamp.org/news/install-xcode-command-line-tools/) +* **ROCm Tools** -* _Macintosh users_ may also need to run the `Install Certificates` command - if model downloads give lots of certificate errors. Run: - `/Applications/Python\ 3.10/Install\ Certificates.command` + For _Linux users with AMD GPUs_, you will need + to install the [ROCm toolkit](./030_INSTALL_CUDA_AND_ROCM.md). Note that + InvokeAI does not support AMD GPUs on Windows systems due to + lack of a Windows ROCm library. + +* **Visual C++ Libraries** + + _Windows users_ must install the free + [Visual C++ libraries from Microsoft](https://learn.microsoft.com/en-US/cpp/windows/latest-supported-vc-redist?view=msvc-170) + +* **The Xcode command line tools** + + for _Macintosh users_. Instructions are available at + [Free Code Camp](https://www.freecodecamp.org/news/install-xcode-command-line-tools/) + + * _Macintosh users_ may also need to run the `Install Certificates` command + if model downloads give lots of certificate errors. Run: + `/Applications/Python\ 3.10/Install\ Certificates.command` ### Installation Walkthrough @@ -75,7 +85,7 @@ manager, please follow these steps: === "Linux/Mac" ```bash - export INVOKEAI_ROOT="~/invokeai" + export INVOKEAI_ROOT=~/invokeai mkdir $INVOKEAI_ROOT ``` @@ -99,35 +109,30 @@ manager, please follow these steps: Windows environment variable using the Advanced System Settings dialogue. Refer to your operating system documentation for details. - - === "Linux/Mac" - ```bash - cd $INVOKEAI_ROOT - python -m venv create .venv - ``` - - === "Windows" - ```bash - cd $INVOKEAI_ROOT - python -m venv create .venv - ``` + ```terminal + cd $INVOKEAI_ROOT + python -m venv .venv --prompt InvokeAI + ``` 4. Activate the new environment: === "Linux/Mac" - ```bash + + ```bash source .venv/bin/activate - ``` + ``` === "Windows" - ```bash - .venv\script\activate - ``` - If you get a permissions error at this point, run the command - `Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope CurrentUser` - and try `activate` again. - The command-line prompt should change to to show `(.venv)` at the + ```ps + .venv\script\activate + ``` + + If you get a permissions error at this point, run this command and try again + + `Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser` + + The command-line prompt should change to to show `(InvokeAI)` at the beginning of the prompt. Note that all the following steps should be run while inside the INVOKEAI_ROOT directory @@ -137,40 +142,47 @@ manager, please follow these steps: python -m pip install --upgrade pip ``` -6. Install the InvokeAI Package. The `--extra-index-url` option is used to select among CUDA, ROCm and CPU/MPS drivers as shown below: +6. Install the InvokeAI Package. The `--extra-index-url` option is used to select among + CUDA, ROCm and CPU/MPS drivers as shown below: === "CUDA (NVidia)" + ```bash pip install InvokeAI[xformers] --use-pep517 --extra-index-url https://download.pytorch.org/whl/cu117 ``` === "ROCm (AMD)" + ```bash pip install InvokeAI --use-pep517 --extra-index-url https://download.pytorch.org/whl/rocm5.2 ``` === "CPU (Intel Macs & non-GPU systems)" + ```bash pip install InvokeAI --use-pep517 --extra-index-url https://download.pytorch.org/whl/cpu ``` === "MPS (M1 and M2 Macs)" + ```bash - pip install InvokeAI --use-pep517 --extra-index-url https://download.pytorch.org/whl/cpu + pip install InvokeAI --use-pep517 ``` 7. Deactivate and reactivate your runtime directory so that the invokeai-specific commands become available in the environment === "Linux/Macintosh" + ```bash deactivate && source .venv/bin/activate ``` === "Windows" - ```bash + + ```ps deactivate - .venv\Scripts\activate + .venv\Scripts\activate ``` 8. Set up the runtime directory @@ -179,7 +191,7 @@ manager, please follow these steps: models, model config files, directory for textual inversion embeddings, and your outputs. - ```bash + ```terminal invokeai-configure ``` @@ -314,7 +326,7 @@ installation protocol (important!) === "MPS (M1 and M2 Macs)" ```bash - pip install -e . --use-pep517 --extra-index-url https://download.pytorch.org/whl/cpu + pip install -e . --use-pep517 ``` Be sure to pass `-e` (for an editable install) and don't forget the @@ -332,3 +344,27 @@ installation protocol (important!) Please see [Contributing](/index.md#Contributing) for hints on getting started. + +### Unsupported Conda Install + +Congratulations, you found the "secret" Conda installation +instructions. If you really **really** want to use Conda with InvokeAI +you can do so using this unsupported recipe: + +``` +mkdir ~/invokeai +conda create -n invokeai python=3.10 +conda activate invokeai +pip install InvokeAI[xformers] --use-pep517 --extra-index-url https://download.pytorch.org/whl/cu117 +invokeai-configure --root ~/invokeai +invokeai --root ~/invokeai --web +``` + +The `pip install` command shown in this recipe is for Linux/Windows +systems with an NVIDIA GPU. See step (6) above for the command to use +with other platforms/GPU combinations. If you don't wish to pass the +`--root` argument to `invokeai` with each launch, you may set the +environment variable INVOKEAI_ROOT to point to the installation directory. + +Note that if you run into problems with the Conda installation, the InvokeAI +staff will **not** be able to help you out. Caveat Emptor!