docs/src/content/docs/development/Setup/dev-environment.mdx
import { LinkCard, Steps, Tabs, TabItem, FileTree, LinkButton } from '@astrojs/starlight/components' import SystemRequirementsLink from '@components/SystemRequirmentsLink.astro'
:::caution Invoke uses a SQLite database. When you run the application as a dev install, you accept responsibility for your database. This means making regular backups (especially before pulling) and/or fixing it yourself in the event that a PR introduces a schema change.
If you don't need to persist your db, you can use an ephemeral in-memory database by setting use_memory_db: true in your invokeai.yaml file. You'll also want to set scan_models_on_startup: true so that your models are registered on startup.
:::
Fork and clone the InvokeAI git repository.
<LinkButton icon="github" iconPlacement="start" href="https://github.com/invoke-ai/InvokeAI/fork" target="_blank" rel="noopener noreferrer"
Fork Repository </LinkButton>
Next, clone your fork to your local machine. You can use either HTTPS or SSH, depending on your git configuration.
This repository uses Git LFS to manage large files. To ensure all assets are downloaded:
git config lfs.fetchinclude "*"
git pull will fetch changes automatically):
git lfs pull
Create a directory for user data (images, models, db, etc). This is typically at ~/invokeai, but if you already have a non-dev install, you may want to create a separate directory for the dev install.
Follow the manual install guide, with some modifications to the install command:
. instead of invokeai to install from the current directory. You don't need to specify the version.uv sync instead of uv pip install so the environment is synchronized from the repository lockfile.dev, test, docs, and appropriate GPU package options with --extra. You may or may not need the xformers option - follow the manual install guide to figure that out.With the modifications made, the sync command should look something like this:
uv sync --frozen \
--python 3.12 \
--managed-python \
--extra dev \
--extra test \
--extra docs \
--extra cuda \
--extra xformers
:::note[Linux ARM64 / aarch64]
On Linux ARM64 devices (e.g. Raspberry Pi 5), use --extra cpu and omit --extra xformers. torch and torchvision are installed from PyPI (CPU-only wheels) — CUDA and ROCm acceleration are not available on this platform.
:::
At this point, you should have Invoke installed, a venv set up and activated, and the server running. But you will see a warning in the terminal that no UI was found. If you go to the URL for the server, you won't get a UI.
This is because the UI build is not distributed with the source code. You need to build it manually. End the running server instance.
(If you only want to edit the docs, you can stop here and skip to the Documentation section below.)
Install the frontend dev toolchain, paying attention to versions:
Do a production build of the frontend:
cd <PATH_TO_INVOKEAI_REPO>/invokeai/frontend/web
pnpm i
pnpm build
Restart the server and navigate to the URL. You should get a UI. After making changes to the python code, restart the server to see those changes.
</Steps>Experimenting with changes to the Python source code is a drag if you have to re-start the server and re-load multi-gigabyte models after every change.
For a faster development workflow, add the --dev_reload flag when starting the server. The server will watch for changes to all the Python files in the invokeai directory and apply those changes to the running server on the fly.
This will allow you to avoid restarting the server (and reloading models) in most cases, but there are some caveats; see the jurigged documentation for details.
The backend tests require the test dependency group, which you installed during the initial setup.
See the Tests documentation for information about running and writing tests.
You'll need to run pnpm build every time you pull in new changes to the frontend.
Another option is to skip the build and instead run the UI in dev mode:
cd invokeai/frontend/web
pnpm dev
This starts a vite dev server for the UI at 127.0.0.1:5173, which you will use instead of 127.0.0.1:9090.
The dev mode is substantially slower than the production build but may be more convenient if you just need to test things out. It will hot-reload the UI as you make changes to the frontend code. Sometimes the hot-reload doesn't work, and you need to manually refresh the browser tab.
This documentation is built on Astro Starlight. It provides a pleasant developer environment for writing engaging documentation, and is built on top of the Astro static site generator, which provides a powerful and flexible framework for building fast, modern websites.
To contribute to the documentation, simply edit the markdown files in the ./docs directory. You can run a local dev server with hot-reloading for changes made to the docs.
```sh
cd docs
pnpm install
```
2. Start the dev server:
```sh
pnpm run dev
```
VSCode offers excellent tools for InvokeAI development, including a python debugger, automatic virtual environment activation, and remote development capabilities.
First, ensure you have the following extensions installed:
It's also highly recommended to install the Jupyter extensions if you plan on working with notebooks:
1. Open the InvokeAI repository directory in VSCode
2. Go to `File` > `Save Workspace As` and save it *outside* the repository
**Default Python Interpreter**
To enable automatic virtual environment activation:
1. Open the command palette (`Ctrl+Shift+P` / `Cmd+Shift+P`) and run `Preferences: Open Workspace Settings (JSON)`
2. Add `python.defaultInterpreterPath` to your settings, pointing to your virtual environment's python executable:
```jsonc
{
"folders": [
{ "path": "InvokeAI" },
{ "path": "/path/to/invokeai_root" }
],
"settings": {
"python.defaultInterpreterPath": "/path/to/invokeai_root/.venv/bin/python"
}
}
```
Now, opening the integrated terminal or running python will automatically use your InvokeAI virtual environment.
Pylance provides type checking in the editor. To enable it:
1. Open a Python file
2. Look along the status bar in VSCode for `{ } Python`
3. Click the `{ }`
4. Turn type checking on (Basic is fine)
You'll now see red squiggly lines where type issues are detected. Hover your cursor over the indicated symbols to see what's wrong.
Add these InvokeAI debugging configurations to your `launch.json`:
```jsonc
{
"version": "0.2.0",
"configurations": [
{
"name": "InvokeAI Web",
"type": "python",
"request": "launch",
"program": "scripts/invokeai-web.py",
"args": [
"--root", "/path/to/invokeai_root",
"--host", "0.0.0.0"
],
"justMyCode": true
},
{
"name": "InvokeAI CLI",
"type": "python",
"request": "launch",
"program": "scripts/invokeai-cli.py",
"justMyCode": true
},
{
"name": "InvokeAI Test",
"type": "python",
"request": "launch",
"module": "pytest",
"args": ["--capture=no"],
"justMyCode": true
},
{
"name": "InvokeAI Single Test",
"type": "python",
"request": "launch",
"module": "pytest",
"args": ["tests/nodes/test_invoker.py"],
"justMyCode": true
}
]
}
```
Consult the [official guide](https://code.visualstudio.com/docs/remote/remote-overview) to get it set up. We suggest using VSCode's included settings sync so that your remote dev host has all the same app settings and extensions automatically.
:::tip[Port Forwarding]
Automatic port forwarding can be flaky. You can disable it in `Preferences: Open Remote Settings (ssh: hostname)` by unticking `remote.autoForwardPorts`.
To forward ports reliably, use SSH on the remote dev client:
```bash
ssh -L 9090:localhost:9090 -L 5173:localhost:5173 user@remote-dev-host
```
Run this outside the VSCode integrated terminal so it persists across VSCode restarts.
:::