diff --git a/docs/docs/migration.md b/docs/docs/migration.md
index 94c5f5e3..6e2a7e30 100644
--- a/docs/docs/migration.md
+++ b/docs/docs/migration.md
@@ -13,6 +13,7 @@
 [sarif-file]: cli.md#-sarif-file
 [gen-patch-path]: cli.md#-gen-patch-path
 [summary-output-file]: cli.md#-o-summary-output-file
+[quick-start]: index.md#quick-start
 
 # Migrating from v1
 
@@ -20,6 +21,38 @@ This page lists what changes when moving from cpp-linter v1 (the Python package)
 project). Most options keep their names, short flags and meaning, so many command lines work
 unchanged. The sections below cover the differences.
 
+## Installing v2
+
+v2 keeps the package name and the command of v1. On PyPI it is still `cpp-linter`, and it still
+installs a `cpp-linter` command. Once 2.0 is released, `pip install --upgrade cpp-linter` moves to
+v2. To stay on v1, pin the version:
+
+```shell
+pip install "cpp-linter<2"
+```
+
+v2 can also be installed with cargo, as a pre-built binary, or from npm. See
+[Quick start][quick-start] for these commands and for how to install the current release candidate.
+
+cpp-linter-action v2 keeps using cpp-linter v1, so workflows that use the action do not change
+until they move to a new major version of the action.
+
+### Python API
+
+v1 is a Python package, so some scripts import its modules, such as `cpp_linter.rest_api`. The v2
+Python package only provides `cpp_linter.main()`. Scripts that import other v1 modules need to run
+cpp-linter as a command or call `main()` instead. `main()` takes an optional list of strings that
+starts with the program name, like `sys.argv`:
+
+```python
+import cpp_linter
+
+cpp_linter.main(["cpp-linter", "--style=file", "src/main.cpp"])
+```
+
+If cpp-linter fails, `main()` raises an `OSError`. Invalid arguments and `--help` exit the Python
+process, as they exit the command.
+
 ## Deprecated options
 
 | v1 option | v2 behavior | What to do |