fix mkdocs formatting (#1927)

* fix mkdocs formatting

* update formatting, add some mkdocs specials

* fix wrong line break, use icon for tab key

Co-authored-by: mauwii <Mauwii@outlook.de>
This commit is contained in:
Lincoln Stein
2022-12-11 13:48:34 -05:00
committed by GitHub
parent 9f855a358a
commit 7efe0f3996
3 changed files with 200 additions and 194 deletions

View File

@ -6,56 +6,79 @@ title: InvokeAI Automated Installation
## Introduction ## Introduction
The automated installer is a shell script that attempts to automate The automated installer is a shell script that attempts to automate every step
every step needed to install and run InvokeAI on a stock computer needed to install and run InvokeAI on a stock computer running recent versions
running recent versions of Linux, MacOS or Windows. It will leave you of Linux, MacOS or Windows. It will leave you with a version that runs a stable
with a version that runs a stable version of InvokeAI with the option version of InvokeAI with the option to upgrade to experimental versions later.
to upgrade to experimental versions later.
## Walk through ## Walk through
1. Make sure that your system meets the [hardware 1. Make sure that your system meets the
requirements](../index.md#hardware-requirements) and has the [hardware requirements](../index.md#hardware-requirements) and has the
appropriate GPU drivers installed. In particular, if you are a Linux appropriate GPU drivers installed. In particular, if you are a Linux user
user with an AMD GPU installed, you may need to install the [ROCm with an AMD GPU installed, you may need to install the
driver](https://rocmdocs.amd.com/en/latest/Installation_Guide/Installation-Guide.html). [ROCm driver](https://rocmdocs.amd.com/en/latest/Installation_Guide/Installation-Guide.html).
- Installation requires roughly 18G of free disk space to load the libraries and !!! info "Required Space"
recommended model weights files.
2. Check that your system has an up-to-date Python installed. To do Installation requires roughly 18G of free disk space to load the libraries and
this, open up a command-line window ("Terminal" on Linux and recommended model weights files.
Macintosh, "Command" or "Powershell" on Windows) and type `python
--version`. If Python is installed, it will print out the version
number. If it is version `3.9.1` or higher, you meet requirements.
- If you see an older version, or you get a command not found 2. Check that your system has an up-to-date Python installed. To do this, open
error, then go to [Python up a command-line window ("Terminal" on Linux and Macintosh, "Command" or
Downloads](https://www.python.org/downloads/) and download the "Powershell" on Windows) and type `python --version`. If Python is
appropriate installer package for your platform. We recommend installed, it will print out the version number. If it is version `3.9.1` or
[Version higher, you meet requirements.
3.10.9](https://www.python.org/downloads/release/python-3109/),
which has been extensively tested with InvokeAI.
-**Windows users**: During the Python configuration process, !!! warning "If you see an older version, or get a command not found error"
Please look out for a checkbox to add Python to your PATH
and select it. If the install script complains that it can't
find python, then open the Python installer again and choose
"Modify" existing installation.
- **Mac users**: After installing Python, you may need to run the Go to [Python Downloads](https://www.python.org/downloads/) and
following command from the Terminal in order to install the Web download the appropriate installer package for your platform. We recommend
certificates needed to download model data from https sites. If [Version 3.10.9](https://www.python.org/downloads/release/python-3109/),
you see lots of CERTIFICATE ERRORS during the last part of the which has been extensively tested with InvokeAI.
install, this is the problem:
`/Applications/Python\ 3.10/Install\ Certificates.command` !!! warning "At this time we do not recommend Python 3.11"
Do not use Python 3.11 at this time due to poor performance === "Windows users"
of the underlying pytorch machine learning library.
- **Linux users**: See [Installing Python in Ubuntu](#installing-python-in-ubuntu) for some - During the Python configuration process,
platform-specific tips. Please look out for a checkbox to add Python to your PATH
and select it. If the install script complains that it can't
find python, then open the Python installer again and choose
"Modify" existing installation.
- There is a slight possibility that you will encountered
DLL load errors at the very end of the installation process. This is caused
by not having up to date Visual C++ redistributable libraries. If this
happens to you, you can install the C++ libraries from this site:
https://learn.microsoft.com/en-us/cpp/windows/deploying-native-desktop-applications-visual-cpp?view=msvc-170
=== "Mac users"
- After installing Python, you may need to run the
following command from the Terminal in order to install the Web
certificates needed to download model data from https sites. If
you see lots of CERTIFICATE ERRORS during the last part of the
install, this is the problem, and you can fix it with this command:
`/Applications/Python\ 3.10/Install\ Certificates.command`
- You may need to install the Xcode command line tools. These
are a set of tools that are needed to run certain applications in a
Terminal, including InvokeAI. This package is provided directly by Apple.
- To install, open a terminal window and run `xcode-select
--install`. You will get a macOS system popup guiding you through the
install. If you already have them installed, you will instead see some
output in the Terminal advising you that the tools are already installed.
- More information can be found here:
https://www.freecodecamp.org/news/install-xcode-command-line-tools/
=== "Linux users"
- See [Installing Python in Ubuntu](#installing-python-in-ubuntu) for some
platform-specific tips.
3. The source installer is distributed in ZIP files. Go to the 3. The source installer is distributed in ZIP files. Go to the
[latest release](https://github.com/invoke-ai/InvokeAI/releases/latest), and [latest release](https://github.com/invoke-ai/InvokeAI/releases/latest), and
@ -67,30 +90,10 @@ number. If it is version `3.9.1` or higher, you meet requirements.
Download the one that is appropriate for your operating system. Download the one that is appropriate for your operating system.
4. If you are a macOS user, you may need to install the Xcode command line tools. 4. Unpack the zip file into a convenient directory. This will create a new
These are a set of tools that are needed to run certain applications in a Terminal, directory named "InvokeAI-Installer". This example shows how this would look
including InvokeAI. This package is provided directly by Apple. using the `unzip` command-line tool, but you may use any graphical or
command-line Zip extractor:
- To install, open a terminal window and run `xcode-select
--install`. You will get a macOS system popup guiding you through
the install. If you already have them installed, you will instead
see some output in the Terminal advising you that the tools are
already installed.
- More information can be found here:
https://www.freecodecamp.org/news/install-xcode-command-line-tools/
5. If you are a Windows users, there is a slight possibility that you
will encountered DLL load errors at the very end of the installation
process. This is caused by not having up to date Visual C++
redistributable libraries. If this happens to you, you can install
the C++ libraries from this site:
https://learn.microsoft.com/en-us/cpp/windows/deploying-native-desktop-applications-visual-cpp?view=msvc-170
6. Unpack the zip file into a convenient directory. This will create
a new directory named "InvokeAI-Installer". This example shows how
this would look using the `unzip` command-line tool, but you may
use any graphical or command-line Zip extractor:
```cmd ```cmd
C:\Documents\Linco> unzip InvokeAI-installer-2.2.4-windows.zip C:\Documents\Linco> unzip InvokeAI-installer-2.2.4-windows.zip
@ -101,63 +104,61 @@ number. If it is version `3.9.1` or higher, you meet requirements.
... ...
``` ```
After successful installation, you can delete the After successful installation, you can delete the `InvokeAI-Installer`
`InvokeAI-Installer` directory. directory.
7. Windows users should now double-click on the file WinLongPathsEnabled.reg 5. **Windows only** Please double-click on the file WinLongPathsEnabled.reg and
and accept the dialog box that asks you if you wish to modify your accept the dialog box that asks you if you wish to modify your registry.
registry. This activates long filename support on your system and will This activates long filename support on your system and will prevent
prevent mysterious errors during installation. mysterious errors during installation.
8. If you are using a desktop GUI, double-click the installer file. It will be 6. If you are using a desktop GUI, double-click the installer file. It will be
named `install.bat` on Windows systems and `install.sh` on Linux and named `install.bat` on Windows systems and `install.sh` on Linux and
Macintosh systems. Macintosh systems.
On Windows systems you will probably get an "Untrusted Publisher" warning. On Windows systems you will probably get an "Untrusted Publisher" warning.
Click on "More Info" and select "Run Anyway." You trust us, right? Click on "More Info" and select "Run Anyway." You trust us, right?
9. Alternatively, from the command line, run the shell script or .bat file: 7. Alternatively, from the command line, run the shell script or .bat file:
```cmd ```cmd
C:\Documents\Linco> cd InvokeAI-Installer C:\Documents\Linco> cd InvokeAI-Installer
C:\Documents\Linco\invokeAI> install.bat C:\Documents\Linco\invokeAI> install.bat
``` ```
10. The script will ask you to choose where to install InvokeAI. Select 8. The script will ask you to choose where to install InvokeAI. Select a
a directory with at least 18G of free space for a full directory with at least 18G of free space for a full install. InvokeAI and
install. InvokeAI and all its support files will be installed into all its support files will be installed into a new directory named
a new directory named `invokeai` located at the location you specify. `invokeai` located at the location you specify.
- The default is to install the `invokeai` directory in your home - The default is to install the `invokeai` directory in your home directory,
directory, usually `C:\Users\YourName\invokeai` on Windows systems, usually `C:\Users\YourName\invokeai` on Windows systems,
`/home/YourName/invokeai` on Linux systems, and `/home/YourName/invokeai` on Linux systems, and `/Users/YourName/invokeai`
`/Users/YourName/invokeai` on Macintoshes, where "YourName" is your on Macintoshes, where "YourName" is your login name.
login name.
- The script uses tab autocompletion to suggest directory path - The script uses tab autocompletion to suggest directory path completions.
completions. Type part of the path (e.g. "C:\Users") and press Type part of the path (e.g. "C:\Users") and press ++tab++ repeatedly
&lt;tab&gt; repeatedly to suggest completions. to suggest completions.
11. Sit back and let the install script work. It will install the 9. Sit back and let the install script work. It will install the third-party
third-party libraries needed by InvokeAI, then download the libraries needed by InvokeAI, then download the current InvokeAI release and
current InvokeAI release and install it. install it.
Be aware that some of the library download and install steps take Be aware that some of the library download and install steps take a long
a long time. In particular, the `pytorch` package is quite large time. In particular, the `pytorch` package is quite large and often appears
and often appears to get "stuck" at 99.9%. Have patience and the to get "stuck" at 99.9%. Have patience and the installation step will
installation step will eventually resume. However, there are eventually resume. However, there are occasions when the library install
occasions when the library install does legitimately get stuck. If does legitimately get stuck. If you have been waiting for more than ten
you have been waiting for more than ten minutes and nothing is minutes and nothing is happening, you can interrupt the script with ^C. You
happening, you can interrupt the script with ^C. You may restart may restart it and it will pick up where it left off.
it and it will pick up where it left off.
12. After installation completes, the installer will launch a script 10. After installation completes, the installer will launch a script called
called `configure_invokeai.py`, which will guide you through the `configure_invokeai.py`, which will guide you through the first-time process
first-time process of selecting one or more Stable Diffusion model of selecting one or more Stable Diffusion model weights files, downloading
weights files, downloading and configuring them. We provide a list and configuring them. We provide a list of popular models that InvokeAI
of popular models that InvokeAI performs well with. However, you performs well with. However, you can add more weight files later on using
can add more weight files later on using the command-line client the command-line client or the Web UI. See
or the Web UI. See [Installing Models](INSTALLING_MODELS.md) for details. [Installing Models](INSTALLING_MODELS.md) for details.
Note that the main Stable Diffusion weights file is protected by a license Note that the main Stable Diffusion weights file is protected by a license
agreement that you must agree to in order to use. The script will list the agreement that you must agree to in order to use. The script will list the
@ -170,64 +171,72 @@ number. If it is version `3.9.1` or higher, you meet requirements.
prompted) and configure InvokeAI to use the previously-downloaded files. The prompted) and configure InvokeAI to use the previously-downloaded files. The
process for this is described in [Installing Models](INSTALLING_MODELS.md). process for this is described in [Installing Models](INSTALLING_MODELS.md).
13. The script will now exit and you'll be ready to generate some 11. The script will now exit and you'll be ready to generate some images. Look
images. Look for the directory `invokeai` installed in the for the directory `invokeai` installed in the location you chose at the
location you chose at the beginning of the install session. Look beginning of the install session. Look for a shell script named `invoke.sh`
for a shell script named `invoke.sh` (Linux/Mac) or `invoke.bat` (Linux/Mac) or `invoke.bat` (Windows). Launch the script by double-clicking
(Windows). Launch the script by double-clicking it or typing its it or typing its name at the command-line:
name at the command-line:
```cmd ```cmd
C:\Documents\Linco> cd invokeai C:\Documents\Linco> cd invokeai
C:\Documents\Linco\invokeAI> invoke.bat C:\Documents\Linco\invokeAI> invoke.bat
``` ```
- The `invoke.bat` (`invoke.sh`) script will give you the choice of starting (1) - The `invoke.bat` (`invoke.sh`) script will give you the choice of starting
the command-line interface, or (2) the web GUI. If you start the latter, you can (1) the command-line interface, or (2) the web GUI. If you start the
load the user interface by pointing your browser at http://localhost:9090. latter, you can load the user interface by pointing your browser at
http://localhost:9090.
- The script also offers you a third option labeled "open the developer - The script also offers you a third option labeled "open the developer
console". If you choose this option, you will be dropped into a console". If you choose this option, you will be dropped into a
command-line interface in which you can run python commands directly, command-line interface in which you can run python commands directly,
access developer tools, and launch InvokeAI with customized options. access developer tools, and launch InvokeAI with customized options.
14. You can launch InvokeAI with several different command-line arguments 12. You can launch InvokeAI with several different command-line arguments that
that customize its behavior. For example, you can change the location customize its behavior. For example, you can change the location of the
of the inage output directory, or select your favorite sampler. See inage output directory, or select your favorite sampler. See the
the [Command-Line Interface](../features/CLI.md) for a full list of [Command-Line Interface](../features/CLI.md) for a full list of the options.
the options.
- To set defaults that will take effect every time you launch InvokeAI, - To set defaults that will take effect every time you launch InvokeAI,
use a text editor (e.g. Notepad) to exit the file use a text editor (e.g. Notepad) to exit the file
`invokeai\invokeai.init`. It contains a variety of examples that you can `invokeai\invokeai.init`. It contains a variety of examples that you can
follow to add and modify launch options. follow to add and modify launch options.
!!! warning "The `invokeai` directory contains the `invoke` application, its
!!! warning "The `invokeai` directory contains the `invoke` application, its configuration files, the model weight files, and outputs of image generation. Once InvokeAI is installed, do not move or remove this directory." configuration files, the model weight files, and outputs of image generation.
Once InvokeAI is installed, do not move or remove this directory."
## Troubleshooting ## Troubleshooting
_Package dependency conflicts_ If you have previously installed ### _Package dependency conflicts_
InvokeAI or another Stable Diffusion package, the installer may
occasionally pick up outdated libraries and either the installer or
`invoke` will fail with complaints about library conflicts. You can
address this by entering the `invokeai` directory and running
`update.sh`, which will bring InvokeAI up to date with the latest
libraries.
!!! warning "Some users have tried to correct dependency problems by installing the `ldm` package from PyPi.org. Unfortunately this is an unrelated package that has nothing to do with the 'latent diffusion model' used by InvokeAI. Installing ldm will make matters worse. If you've installed ldm, uninstall it with `pip uninstall ldm`." If you have previously installed InvokeAI or another Stable Diffusion package,
the installer may occasionally pick up outdated libraries and either the
installer or `invoke` will fail with complaints about library conflicts. You can
address this by entering the `invokeai` directory and running `update.sh`, which
will bring InvokeAI up to date with the latest libraries.
_"Corrupted configuration file."__ Everything seems to install ok, but ### ldm from pypi
`invoke` complains of a corrupted configuration file and goes back
into the configuration process (asking you to download models, etc),
but this doesn't fix the problem.
This issue is often caused by a misconfigured configuration directive !!! warning
in the `invokeai\invokeai.init` initialization file that contains
startup settings. The easiest way to fix the problem is to move the Some users have tried to correct dependency problems by installing
file out of the way and re-run `configure_invokeai.py`. Enter the the `ldm` package from PyPi.org. Unfortunately this is an unrelated package that
developer's console (option 3 of the launcher script) and run this has nothing to do with the 'latent diffusion model' used by InvokeAI. Installing
command: ldm will make matters worse. If you've installed ldm, uninstall it with
`pip uninstall ldm`.
### Corrupted configuration file
Everything seems to install ok, but `invoke` complains of a corrupted
configuration file and goes back into the configuration process (asking you to
download models, etc), but this doesn't fix the problem.
This issue is often caused by a misconfigured configuration directive in the
`invokeai\invokeai.init` initialization file that contains startup settings. The
easiest way to fix the problem is to move the file out of the way and re-run
`configure_invokeai.py`. Enter the developer's console (option 3 of the launcher
script) and run this command:
```cmd ```cmd
configure_invokeai.py --root=. configure_invokeai.py --root=.
@ -235,45 +244,12 @@ configure_invokeai.py --root=.
Note the dot (.) after `--root`. It is part of the command. Note the dot (.) after `--root`. It is part of the command.
_If none of these maneuvers fixes the problem_ then please report the _If none of these maneuvers fixes the problem_ then please report the problem to
problem to the [InvokeAI the [InvokeAI Issues](https://github.com/invoke-ai/InvokeAI/issues) section, or
Issues](https://github.com/invoke-ai/InvokeAI/issues) section, or visit our [Discord Server](https://discord.gg/ZmtBAhwWhy) for interactive
visit our [Discord Server](https://discord.gg/ZmtBAhwWhy) for interactive assistance. assistance.
## Updating to newer versions ### other problems
This distribution is changing rapidly, and we add new features on a daily basis.
To update to the latest released version (recommended), run the `update.sh`
(Linux/Mac) or `update.bat` (Windows) scripts. This will fetch the latest
release and re-run the `configure_invokeai` script to download any updated models
files that may be needed. You can also use this to add additional models that
you did not select at installation time.
You can now close the developer console and run `invoke` as before. If you get
complaints about missing models, then you may need to do the additional step of
running `configure_invokeai.py`. This happens relatively infrequently. To do this,
simply open up the developer's console again and type
`python scripts/configure_invokeai.py`.
You may also use the `update` script to install any selected version
of InvokeAI. From https://github.com/invoke-ai/InvokeAI, navigate to
the zip file link of the version you wish to install. You can find the
zip links by going to the one of the release pages and looking for the
**Assets** section at the bottom. Alternatively, you can browse
"branches" and "tags" at the top of the big code directory on the
InvokeAI welcome page. When you find the version you want to install,
go to the green "&lt;&gt; Code" button at the top, and copy the
"Download ZIP" link.
Now run `update.sh` (or `update.bat`) with the URL of the desired
InvokeAI version as its argument. For example, this will install the
old 2.2.0 release.
```cmd
update.sh https://github.com/invoke-ai/InvokeAI/archive/refs/tags/v2.2.0.zip
```
## Troubleshooting
If you run into problems during or after installation, the InvokeAI team is If you run into problems during or after installation, the InvokeAI team is
available to help you. Either create an available to help you. Either create an
@ -283,16 +259,46 @@ make a request for help on the "bugs-and-support" channel of our
organization, but typically somebody will be available to help you within 24 organization, but typically somebody will be available to help you within 24
hours, and often much sooner. hours, and often much sooner.
## Updating to newer versions
This distribution is changing rapidly, and we add new features on a daily basis.
To update to the latest released version (recommended), run the `update.sh`
(Linux/Mac) or `update.bat` (Windows) scripts. This will fetch the latest
release and re-run the `configure_invokeai` script to download any updated
models files that may be needed. You can also use this to add additional models
that you did not select at installation time.
You can now close the developer console and run `invoke` as before. If you get
complaints about missing models, then you may need to do the additional step of
running `configure_invokeai.py`. This happens relatively infrequently. To do
this, simply open up the developer's console again and type
`python scripts/configure_invokeai.py`.
You may also use the `update` script to install any selected version of
InvokeAI. From https://github.com/invoke-ai/InvokeAI, navigate to the zip file
link of the version you wish to install. You can find the zip links by going to
the one of the release pages and looking for the **Assets** section at the
bottom. Alternatively, you can browse "branches" and "tags" at the top of the
big code directory on the InvokeAI welcome page. When you find the version you
want to install, go to the green "&lt;&gt; Code" button at the top, and copy the
"Download ZIP" link.
Now run `update.sh` (or `update.bat`) with the URL of the desired InvokeAI
version as its argument. For example, this will install the old 2.2.0 release.
```cmd
update.sh https://github.com/invoke-ai/InvokeAI/archive/refs/tags/v2.2.0.zip
```
## Installing Python in Ubuntu ## Installing Python in Ubuntu
For reasons that are not entirely clear, installing the correct For reasons that are not entirely clear, installing the correct version of
version of Python can be a bit of a challenge on Ubuntu, Linux Mint, and Python can be a bit of a challenge on Ubuntu, Linux Mint, and other
other Ubuntu-derived distributions. Ubuntu-derived distributions.
In particular, Ubuntu version 20.04 LTS comes with an old version of In particular, Ubuntu version 20.04 LTS comes with an old version of Python,
Python, does not come with the PIP package manager installed, and to does not come with the PIP package manager installed, and to make matters worse,
make matters worse, the `python` command points to Python2, not the `python` command points to Python2, not Python3.
Python3.
Here is the quick recipe for bringing your system up to date: Here is the quick recipe for bringing your system up to date:
@ -305,6 +311,5 @@ sudo ln -sf python3.9 python3
sudo ln -sf python3 python sudo ln -sf python3 python
``` ```
You can still access older versions of Python by calling `python2`, You can still access older versions of Python by calling `python2`, `python3.8`,
`python3.8`, etc. etc.

View File

@ -14,8 +14,8 @@ if "%1" == "use-cache" (
@rem Config @rem Config
@rem this should be changed to the tagged release! @rem this should be changed to the tagged release!
@rem set INVOKE_AI_SRC=https://github.com/invoke-ai/InvokeAI/archive/main.zip set INVOKE_AI_SRC=https://github.com/invoke-ai/InvokeAI/archive/main.zip
set INVOKE_AI_SRC=https://github.com/invoke-ai/InvokeAI/archive/refs/tags/2.2.4-rc1.zip @rem set INVOKE_AI_SRC=https://github.com/invoke-ai/InvokeAI/archive/refs/tags/v2.2.4.zip
set INSTRUCTIONS=https://invoke-ai.github.io/InvokeAI/installation/INSTALL_AUTOMATED/ set INSTRUCTIONS=https://invoke-ai.github.io/InvokeAI/installation/INSTALL_AUTOMATED/
set TROUBLESHOOTING=https://invoke-ai.github.io/InvokeAI/installation/INSTALL_AUTOMATED/#troubleshooting set TROUBLESHOOTING=https://invoke-ai.github.io/InvokeAI/installation/INSTALL_AUTOMATED/#troubleshooting
set PYTHON_URL=https://www.python.org/downloads/windows/ set PYTHON_URL=https://www.python.org/downloads/windows/

View File

@ -9,7 +9,8 @@ cd "$scriptdir"
deactivate >/dev/null 2>&1 deactivate >/dev/null 2>&1
# this should be changed to the tagged release! # this should be changed to the tagged release!
INVOKE_AI_SRC=https://github.com/invoke-ai/InvokeAI/archive/refs/tags/2.2.4-rc1.zip INVOKE_AI_SRC=https://github.com/invoke-ai/InvokeAI/archive/main.zip
# INVOKE_AI_SRC=https://github.com/invoke-ai/InvokeAI/archive/refs/tags/v2.2.4.zip
INSTRUCTIONS=https://invoke-ai.github.io/InvokeAI/installation/INSTALL_AUTOMATED/ INSTRUCTIONS=https://invoke-ai.github.io/InvokeAI/installation/INSTALL_AUTOMATED/
TROUBLESHOOTING=https://invoke-ai.github.io/InvokeAI/installation/INSTALL_AUTOMATED/#troubleshooting TROUBLESHOOTING=https://invoke-ai.github.io/InvokeAI/installation/INSTALL_AUTOMATED/#troubleshooting
MINIMUM_PYTHON_VERSION=3.9.0 MINIMUM_PYTHON_VERSION=3.9.0