incomplete work on manual install

docs/index.md

@@ -81,28 +81,6 @@ Q&A</a>]
 
     This fork is rapidly evolving. Please use the [Issues tab](https://github.com/invoke-ai/InvokeAI/issues) to report bugs and make feature requests. Be sure to use the provided templates. They will help aid diagnose issues faster.
 
-## :octicons-package-dependencies-24: Installation
-
-This fork is supported across Linux, Windows and Macintosh. Linux users can use
-either an Nvidia-based card (with CUDA support) or an AMD card (using the ROCm
-driver).
-
-First time users, please see
-[Automated Installer](installation/INSTALL_AUTOMATED.md) for a walkthrough of
-getting InvokeAI up and running on your system. For alternative installation and
-upgrade instructions, please see:
-[InvokeAI Installation Overview](installation/)
-
-Users who wish to make use of the **PyPatchMatch** inpainting functions
-will need to perform a bit of extra work to enable this
-module. Instructions can be found at [Installing
-PyPatchMatch](installation/060_INSTALL_PATCHMATCH.md).
-
-If you have an NVIDIA card, you can benefit from the significant
-memory savings and performance benefits provided by Facebook Lab's
-**xFormers** module. Instructions for Linux and Windows users can be found
-at [Installing xFormers](installation/070_INSTALL_XFORMERS.md).
-
 ## :fontawesome-solid-computer: Hardware Requirements
 
 ### :octicons-cpu-24: System
@@ -141,6 +119,28 @@ images in full-precision mode:
     (invokeai) ~/InvokeAI$ python scripts/invoke.py --full_precision
     ```
 
+## :octicons-package-dependencies-24: Installation
+
+This fork is supported across Linux, Windows and Macintosh. Linux users can use
+either an Nvidia-based card (with CUDA support) or an AMD card (using the ROCm
+driver).
+
+First time users, please see
+[Automated Installer](installation/INSTALL_AUTOMATED.md) for a walkthrough of
+getting InvokeAI up and running on your system. For alternative installation and
+upgrade instructions, please see:
+[InvokeAI Installation Overview](installation/)
+
+Users who wish to make use of the **PyPatchMatch** inpainting functions
+will need to perform a bit of extra work to enable this
+module. Instructions can be found at [Installing
+PyPatchMatch](installation/060_INSTALL_PATCHMATCH.md).
+
+If you have an NVIDIA card, you can benefit from the significant
+memory savings and performance benefits provided by Facebook Lab's
+**xFormers** module. Instructions for Linux and Windows users can be found
+at [Installing xFormers](installation/070_INSTALL_XFORMERS.md).
+
 ## :octicons-gift-24: InvokeAI Features
 
 - [The InvokeAI Web Interface](features/WEB.md) -
@@ -166,89 +166,79 @@ images in full-precision mode:
 
 ## :octicons-log-16: Latest Changes
 
-### v2.2.4 <small>(11 December 2022)</small>
+### v2.3.0 <small>(XX February 2023)</small>
 
-#### the `invokeai` directory
+#### Migration to Stable Diffusion `diffusers` models
 
-Previously there were two directories to worry about, the directory that
+Previous versions of InvokeAI supported the original model file format introduced with Stable Diffusion 1.4. In the original format, known variously as "checkpoint", or "legacy" format, there is a single large weights file ending with `.ckpt` or `.safetensors`. Though this format has served the community well, it has a number of disadvantages, including file size, slow loading times, and a variety of non-standard variants that require special-case code to handle. In addition, because checkpoint files are actually a bundle of multiple machine learning sub-models, it is hard to swap different sub-models in and out, or to share common sub-models. A new format, introduced by the StabilityAI company in collaboration with HuggingFace, is called `diffusers` and consists of a directory of individual models. The most immediate benefit of `diffusers` is that they load from disk very quickly. A longer term benefit is that in the near future `diffusers` models will be able to share common sub-models, dramatically reducing disk space when you have multiple fine-tune models derived from the same base.
-contained the InvokeAI source code and the launcher scripts, and the `invokeai`
-directory that contained the models files, embeddings, configuration and
-outputs. With the 2.2.4 release, this dual system is done away with, and
-everything, including the `invoke.bat` and `invoke.sh` launcher scripts, now
-live in a directory named `invokeai`. By default this directory is located in
-your home directory (e.g. `\Users\yourname` on Windows), but you can select
-where it goes at install time.
 
-After installation, you can delete the install directory (the one that the zip
+When you perform a new install of version 2.3.0, you will be offered the option to install the `diffusers` versions of a number of popular SD models, including Stable Diffusion versions 1.5 and 2.1 (including the 768x768 pixel version of 2.1). These will act and work just like the checkpoint versions. Do not be concerned if you already have a lot of ".ckpt" or ".safetensors" models on disk! InvokeAI 2.3.0 can still load these and generate images from them without any extra intervention on your part.
-file creates when it unpacks). Do **not** delete or move the `invokeai`
-directory!
 
-##### Initialization file `invokeai/invokeai.init`
+To take advantage of the optimized loading times of `diffusers` models, InvokeAI offers options to convert legacy checkpoint models into optimized `diffusers` models. If you use the `invokeai` command line interface, the relevant commands are:
 
-You can place frequently-used startup options in this file, such as the default
+* `!convert_model` -- Take the path to a local checkpoint file or a URL that is pointing to one, convert it into a `diffusers` model, and import it into InvokeAI's models registry file.
-number of steps or your preferred sampler. To keep everything in one place, this
+* `!optimize_model` -- If you already have a checkpoint model in your InvokeAI models file, this command will accept its short name and convert it into a like-named `diffusers` model, optionally deleting the original checkpoint file.
-file has now been moved into the `invokeai` directory and is named
+* `!import_model` -- Take the local path of either a checkpoint file or a `diffusers` model directory and import it into InvokeAI's registry file. You may also provide the ID of any diffusers model that has been published on the [HuggingFace models repository](https://huggingface.co/models?pipeline_tag=text-to-image&sort=downloads) and it will be downloaded and installed automatically.
-`invokeai.init`.
 
-#### To update from Version 2.2.3
+The WebGUI offers similar functionality for model management.
 
-The easiest route is to download and unpack one of the 2.2.4 installer files.
+For advanced users, new command-line options provide additional functionality. Launching `invokeai` with the argument `--autoconvert <path to directory>` takes the path to a directory of checkpoint files, automatically converts them into `diffusers` models and imports them. Each time the script is launched, the directory will be scanned for new checkpoint files to be loaded. Alternatively, the `--ckpt_convert` argument will cause any checkpoint or safetensors model that is already registered with InvokeAI to be converted into a `diffusers` model on the fly, allowing you to take advantage of future diffusers-only features without explicitly converting the model and saving it to disk.
-When it asks you for the location of the `invokeai` runtime directory, respond
-with the path to the directory that contains your 2.2.3 `invokeai`. That is, if
-`invokeai` lives at `C:\Users\fred\invokeai`, then answer with `C:\Users\fred`
-and answer "Y" when asked if you want to reuse the directory.
 
-The `update.sh` (`update.bat`) script that came with the 2.2.3 source installer
+Please see [INSTALLING MODELS](https://invoke-ai.github.io/InvokeAI/installation/050_INSTALLING_MODELS/) for more information on model management in both the command-line and Web interfaces.
-does not know about the new directory layout and won't be fully functional.
 
-#### To update to 2.2.5 (and beyond) there's now an update path.
+#### Support for the `XFormers` Memory-Efficient Crossattention Package
 
-As they become available, you can update to more recent versions of InvokeAI
+On CUDA (Nvidia) systems, version 2.3.0 supports the `XFormers` library. Once installed,  the`xformers` package dramatically reduces the memory footprint of loaded Stable Diffusion models files and modestly increases image generation speed. `xformers` will be installed and activated automatically if you specify a CUDA system at install time.
-using an `update.sh` (`update.bat`) script located in the `invokeai` directory.
-Running it without any arguments will install the most recent version of
-InvokeAI. Alternatively, you can get set releases by running the `update.sh`
-script with an argument in the command shell. This syntax accepts the path to
-the desired release's zip file, which you can find by clicking on the green
-"Code" button on this repository's home page.
 
-#### Other 2.2.4 Improvements
+The caveat with using `xformers` is that it introduces slightly non-deterministic behavior, and images generated using the same seed and other settings will be subtly different between invocations. Generally the changes are unnoticeable unless you rapidly shift back and forth between images, but to disable `xformers` and restore fully deterministic behavior, you may launch InvokeAI using the `--no-xformers` option. This is most conveniently done by opening the file `invokeai/invokeai.init` with a text editor, and adding the line `--no-xformers` at the bottom.
 
-- Fix InvokeAI GUI initialization by @addianto in #1687
+#### A Negative Prompt Box in the WebUI
-- fix link in documentation by @lstein in #1728
-- Fix broken link by @ShawnZhong in #1736
-- Remove reference to binary installer by @lstein in #1731
-- documentation fixes for 2.2.3 by @lstein in #1740
-- Modify installer links to point closer to the source installer by @ebr in
-  #1745
-- add documentation warning about 1650/60 cards by @lstein in #1753
-- Fix Linux source URL in installation docs by @andybearman in #1756
-- Make install instructions discoverable in readme by @damian0815 in #1752
-- typo fix by @ofirkris in #1755
-- Non-interactive model download (support HUGGINGFACE_TOKEN) by @ebr in #1578
-- fix(srcinstall): shell installer - cp scripts instead of linking by @tildebyte
-  in #1765
-- stability and usage improvements to binary & source installers by @lstein in
-  #1760
-- fix off-by-one bug in cross-attention-control by @damian0815 in #1774
-- Eventually update APP_VERSION to 2.2.3 by @spezialspezial in #1768
-- invoke script cds to its location before running by @lstein in #1805
-- Make PaperCut and VoxelArt models load again by @lstein in #1730
-- Fix --embedding_directory / --embedding_path not working by @blessedcoolant in
-  #1817
-- Clean up readme by @hipsterusername in #1820
-- Optimized Docker build with support for external working directory by @ebr in
-  #1544
-- disable pushing the cloud container by @mauwii in #1831
-- Fix docker push github action and expand with additional metadata by @ebr in
-  #1837
-- Fix Broken Link To Notebook by @VedantMadane in #1821
-- Account for flat models by @spezialspezial in #1766
-- Update invoke.bat.in isolate environment variables by @lynnewu in #1833
-- Arch Linux Specific PatchMatch Instructions & fixing conda install on linux by
-  @SammCheese in #1848
-- Make force free GPU memory work in img2img by @addianto in #1844
-- New installer by @lstein
 
+There is now a separate text input box for negative prompts in the WebUI. This is convenient for stashing frequently-used negative prompts ("mangled limbs, bad anatomy"). The `[negative prompt]` syntax continues to work in the main prompt box as well.
+
+To see exactly how your prompts are being parsed, launch `invokeai` with the `--log_tokenization` option. The console window will then display the tokenization process for both positive and negative prompts.
+
+#### Model Merging
+
+Version 2.3.0 offers an intuitive user interface for merging up to three Stable Diffusion models using an intuitive user interface. Model merging allows you to mix the behavior of models to achieve very interesting effects. To use this, each of the models must already be imported into InvokeAI and saved in `diffusers` format, then launch the merger using a new menu item in the InvokeAI launcher script (`invoke.sh`, `invoke.bat`) or directly from the command line with `invokeai-merge --gui`. You will be prompted to select the models to merge, the proportions in which to mix them, and the mixing algorithm. The script will create a new merged `diffusers` model and import it into InvokeAI for your use.
+
+See [MODEL MERGING](https://invoke-ai.github.io/InvokeAI/features/MODEL_MERGING/) for more details.
+
+#### Textual Inversion Training
+
+Textual Inversion (TI) is a technique for training a Stable Diffusion model to emit a particular subject or style when triggered by a keyword phrase. You can perform TI training by placing a small number of images of the subject or style in a directory, and choosing a distinctive trigger phrase, such as "pointillist-style". After successful training, The subject or style will be activated by including `<pointillist-style>` in your prompt.
+
+Previous versions of InvokeAI were able to perform TI, but it required using a command-line script with dozens of obscure command-line arguments. Version 2.3.0 features an intuitive TI frontend that will build a TI model on top of any `diffusers` model. To access training you can launch from a new item in the launcher script or from the command line using `invokeai-ti --gui`.
+
+See [TEXTUAL INVERSION](https://invoke-ai.github.io/InvokeAI/features/TEXTUAL_INVERSION/) for further details.
+
+#### A New Installer Experience
+
+The InvokeAI installer has been upgraded in order to provide a smoother and hopefully more glitch-free experience. In addition, InvokeAI is now packaged as a PyPi project, allowing developers and power-users to install InvokeAI with the command `pip install InvokeAI  --use-pep517`. Please see [Installation](#installation) for details.
+
+Developers should be aware that the `pip` installation procedure has been simplified and that the `conda` method is no longer supported at all. Accordingly, the `environments_and_requirements` directory has been deleted from the repository.
+
+#### Command-line name changes
+
+All of InvokeAI's functionality, including the WebUI, command-line interface, textual inversion training and model merging, can all be accessed from the `invoke.sh` and `invoke.bat` launcher scripts. The menu of options has been expanded to add the new functionality. For the convenience of developers and power users, we have normalized the names of the InvokeAI command-line scripts:
+
+* `invokeai` -- Command-line client
+* `invokeai --web` -- Web GUI
+* `invokeai-merge --gui` -- Model merging script with graphical front end
+* `invokeai-ti --gui` -- Textual inversion script with graphical front end
+* `invokeai-configure` -- Configuration tool for initializing the `invokeai` directory and selecting popular starter models.
+
+For backward compatibility, the old command names are also recognized, including `invoke.py` and `configure-invokeai.py`. However, these are deprecated and will eventually be removed.
+
+Developers should be aware that the locations of the script's source code has been moved. The new locations are:
+* `invokeai` =>  `ldm/invoke/CLI.py`
+* `invokeai-configure` => `ldm/invoke/config/configure_invokeai.py`
+* `invokeai-ti`=> `ldm/invoke/training/textual_inversion.py`
+* `invokeai-merge` => `ldm/invoke/merge_diffusers`
+
+Developers are strongly encouraged to perform an "editable" install of InvokeAI using `pip install -e .  --use-pep517` in the Git repository, and then to call the scripts using their 2.3.0 names, rather than executing the scripts directly. Developers should also be aware that the several important data files have been relocated into a new directory named `invokeai`. This includes the WebGUI's `frontend` and `backend` directories, and the `INITIAL_MODELS.yaml` files used by the installer to select starter models. Eventually all InvokeAI modules will be in subdirectories of `invokeai`.
+
+Please see [2.3.0 Release Notes](https://github.com/invoke-ai/InvokeAI/releases/tag/v2.3.0) for further details.
 For older changelogs, please visit the
 **[CHANGELOG](CHANGELOG/#v223-2-december-2022)**.
 

docs/installation/020_INSTALL_MANUAL.md

@@ -14,17 +14,46 @@ title: Installing Manually
 
 ## Introduction
 
-!!! tip As of InvokeAI v2.3.0 installation using the `conda` package manager
+!!! tip "Conda"
-is no longer being supported. It will likely still work, but we are not testing
+    As of InvokeAI v2.3.0 installation using the `conda` package manager is no longer being supported. It will likely still work, but we are not testing this installation method.
-this installation method.
 
 On Windows systems, you are encouraged to install and use the
 [PowerShell](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows?view=powershell-7.3),
-which provides compatibility with Linux and Mac shells and nice features such as
+which provides compatibility with Linux and Mac shells and nice
-command-line completion.
+features such as command-line completion.
 
-To install InvokeAI with virtual environments and the PIP package manager,
+### Prequisites
-please follow these steps:
+
+Before you start, make sure you have the following preqrequisites
+installed.  These are described in more detail in [Automated
+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).
+
+* **CUDA Tools** For those with _NVidia GPUs_, you will need to
+  install the [CUDA toolkit and optionally the XFormers library](070_INSTALL_XFORMERS.md).
+
+*  **ROCm Tools** For _Linux users with AMD GPUs_, you will need
+   to install the [ROCm toolkit](080_INSTALL_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
+
+To install InvokeAI with virtual environments and the PIP package
+manager, please follow these steps:
 
 1.  Please make sure you are using Python 3.9 or 3.10. The rest of the install
     procedure depends on this and will not work with other versions:
@@ -33,74 +62,103 @@ please follow these steps:
     python -V
     ```
 
-2.  Clone the [InvokeAI](https://github.com/invoke-ai/InvokeAI) source code from
+2.  Create a directory to contain your InvokeAI library, configuration
-    GitHub:
+    files, and models. This is known as the "runtime" or "root"
+    directory, and often lives in your home directory under the name `invokeai`.
 
+    Please keep in mind the disk space requirements - you will need at
+    least 20GB for the models and the virtual environment.  From now
+    on we will refer to this directory as `INVOKEAI_ROOT`.
+
+    === "Linux/Mac"
+    
+        ```bash
+        export INVOKEAI_ROOT="~/invokeai"
+        mkdir ${INVOKEAI_ROOT}
+        ```
+
+    === "Windows"
+    
+        ```bash
+        set INVOKEAI_ROOT=%HomeDrive%%HomePath%/invokeai
+        mkdir %INVOKEAI_ROOT%
+        ```
+
+3. Enter the invokeai directory and create a virtual Python
+   environment within it named `.venv`. If the command `python`
+   doesn't work, try `python3`. Note that while you may create the
+   virtual environment anywhere in the file system, we recommend that
+   you create it within the root directory as shown here. This makes
+   it possible for the InvokeAI applications to find the model data
+   and configuration. If you do not choose to install the virtual
+   environment inside the root directory, then you **must** set the
+   `INVOKEAI_ROOT` environment variable in your shell environment, for
+   example, by editing `~/.bashrc` or `~/.zshrc` files, or setting the
+   Windows environment variable. Refer to your operating system /
+   shell documentation for the correct way of doing so.
+
+
+    Linux or Mac:
+     ```bash
+     cd $INVOKEAI_ROOT
+     python -m venv create .venv
+     ```
+
+    Windows:
+     ```bash
+     cd %INVOKEAI_ROOT%
+     python -m venv create .venv
+     ```
+
+4.  Activate the new environment:
+
+    Linux, Mac:
+    
     ```bash
-    git clone https://github.com/invoke-ai/InvokeAI.git
+    source $INVOKEAI_ROOT/.venv/bin/activate
     ```
 
-    This will create InvokeAI folder where you will follow the rest of the
+    Windows:
-    steps.
-
-3.  Create a directory of to contain your InvokeAI installation (known as the "runtime"
-    or "root" directory). This is where your models, configs, and outputs will live
-    by default. Please keep in mind the disk space requirements - you will need at
-    least 18GB (as of this writing) for the models and the virtual environment.
-    From now on we will refer to this directory as `INVOKEAI_ROOT`. This keeps the
-    runtime directory separate from the source code and aids in updating.
-
     ```bash
-    export INVOKEAI_ROOT="~/invokeai"
+    %INVOKEAI_ROOT%/.venv/scripts/activate
-    mkdir ${INVOKEAI_ROOT}
     ```
 
-4.  From within the InvokeAI top-level directory, create and activate a virtual
+    The command-line prompt should change to to show `(.venv)` at the
-    environment named `.venv` and prompt displaying `InvokeAI`:
+    beginning of the prompt.
 
-    ```bash
+5.  Make sure that pip is installed in your virtual environment and up to date:
-    python -m venv ${INVOKEAI_ROOT}/.venv \
-        --prompt invokeai \
-        --upgrade-deps \
-        --copies
-    source ${INVOKEAI_ROOT}/.venv/bin/activate
-    ```
-
-    !!! warning
-
-        You **may** create your virtual environment anywhere on the filesystem.
-        But IF you choose a location that is *not* inside the `$INVOKEAI_ROOT` directory,
-        then you must set the `INVOKEAI_ROOT` environment variable in your shell environment,
-        for example, by editing `~/.bashrc` or `~/.zshrc` files, or setting the Windows environment
-        variable. Refer to your operating system / shell documentation for the correct way of doing so.
-
-5.  Make sure that pip is installed in your virtual environment an up to date:
 
     ```bash
     python -m pip install --upgrade pip
     ```
 
-6.  Install Package
+6.  Install the InvokeAI Package
 
     ```bash
-    pip install --use-pep517 .
+    pip install --use-pep517 --upgrade InvokeAI
     ```
 
-    Deactivate and reactivate your runtime directory so that the invokeai-specific commands
+7.  Deactivate and reactivate your runtime directory so that the invokeai-specific commands
     become available in the environment
 
-    ```
+    Linux/Macintosh:
+    ```bash
     deactivate && source ${INVOKEAI_ROOT}/.venv/bin/activate
     ```
 
-7.  Set up the runtime directory
+    Windows:
+    ```bash
+    deactivate && %INVOKEAI_ROOT%/.venv/Scripts/activate
+    ```
+
+8.  Set up the runtime directory
 
     In this step you will initialize your runtime directory with the downloaded
     models, model config files, directory for textual inversion embeddings, and
     your outputs.
 
     ```bash
-    invokeai-configure --root ${INVOKEAI_ROOT}
+    invokeai-configure
     ```
 
     The script `invokeai-configure` will interactively guide you through the
@@ -121,7 +179,7 @@ please follow these steps:
         prompted) and configure InvokeAI to use the previously-downloaded files. The
         process for this is described in [here](050_INSTALLING_MODELS.md).
 
-7.  Run the command-line- or the web- interface:
+9.  Run the command-line- or the web- interface:
 
     Activate the environment (with `source .venv/bin/activate`), and then run
     the script `invokeai`. If you selected a non-default location for the
@@ -158,17 +216,12 @@ please follow these steps:
         You can permanently set the location of the runtime directory by setting the environment variable `INVOKEAI_ROOT` to the path of the directory. As mentioned previously, this is
         **required** if your virtual environment is located outside of your runtime directory.
 
-8.  Render away!
+10.  Render away!
 
     Browse the [features](../features/CLI.md) section to learn about all the
     things you can do with InvokeAI.
 
-    Note that some GPUs are slow to warm up. In particular, when using an AMD
+11.  Subsequently, to relaunch the script, activate the virtual environment, and
-    card with the ROCm driver, you may have to wait for over a minute the first
-    time you try to generate an image. Fortunately, after the warm-up period
-    rendering will be fast.
-
-9.  Subsequently, to relaunch the script, activate the virtual environment, and
     then launch `invokeai` command. If you forget to activate the virtual
     environment you will most likeley receive a `command not found` error.