How To Migrate to v1¶

This guide covers the breaking changes between the v0.x and v1.x versions of the language server and how to adapt to them.

Installation Changes¶

Previously, it was recommended to install esbonio as a development dependency for each project you wished to use with. This was because esbonio would run Sphinx as part of its own process and therefore need access to your project’s dependencies.

In v1.x Sphinx is now run in a separate process so this is no longer necessary, in fact, it’s recommended you remove it from your project specific environments:

(env) $ pip uninstall esbonio

Instead, you can now have a single, global installation that is reused across projects. It’s recommended that you use tools like pipx or uv to manage this installation for you

pipx

$ pipx install esbonio   # Installs esbonio globally in an isolated environment
$ pipx upgrade esbonio   # Upgrade esbonio and its dependencies

$ uv tool install esbonio    # Installs esbonio globally in an isolated environment
$ uv tool upgrade esbonio    # Upgrade esbonio and its dependencies

Note

If you use the Esbonio VSCode extension, the language server is automatically included as part of the extension itself, no separate installation required!

Configuration Changes¶

Tip

With the release of v1.x, Esbonio’s configuration system has been overhauled, see Configuration for all of the available configuration options and methods.

While esbonio can now be installed globally, it still needs access to your project’s development environment in order launch Sphinx correctly. This means the two most imporant configuration values are

esbonio.sphinx.pythonCommand: For telling esbonio the command it needs to run in order to use the correct Python environment.
esbonio.sphinx.buildCommand: For telling esbonio the sphinx-build command you use to build your documentation. This is so that the server invoke Sphinx with the correct arguments.

The following table outlines the configuration options that have been removed in v1.x and what their correpsonding replacement is

Removed Option	Replacement	Notes
`esbonio.sphinx.builderName` `esbonio.sphinx.srcDir` `esbonio.sphinx.buildDir`	`esbonio.sphinx.buildCommand`	Pass `-b <builderName> <srcDir> <buildDir>` to `sphinx-build`
`esbonio.sphinx.confDir`	`esbonio.sphinx.buildCommand`	Use `-c <confDir>`
`esbonio.sphinx.doctreeDir`	`esbonio.sphinx.buildCommand`	Use `-d <doctreeDir>`
`esbonio.sphinx.forceFullBuild`	`esbonio.sphinx.buildCommand`	Use `-E`
`esbonio.sphinx.keepGoing`	`esbonio.sphinx.buildCommand`	Use `--keep-going`
`esbonio.sphinx.makeMode`	`esbonio.sphinx.buildCommand`	Pass `-M <builderName> <srcDir> <buildDir>` to `sphinx-build`
`esbonio.sphinx.numJobs`	`esbonio.sphinx.buildCommand`	Use `-j <numJobs>`
`esbonio.sphinx.quiet`	`esbonio.sphinx.buildCommand`	Use `-q`
`esbonio.sphinx.tags`	`esbonio.sphinx.buildCommand`	Use `-t`
`esbonio.sphinx.verbosity`	`esbonio.sphinx.buildCommand`	Use `-v`
`esbonio.sphinx.warningIsError`	`esbonio.sphinx.buildCommand`	Use `-W`
`esbonio.server.hideSphinxOutput` `esbonio.sphinx.silent`	`esbonio.sphinx.buildCommand`	Use `-Q`
`esbonio.server.logLevel`	`esbonio.logging.level`
`esbonio.server.logFilter`	`esbonio.logging.config`
`esbonio.server.enabledInPyFiles`	`esbonio.server.documentSelector`	VSCode only
`esbonio.server.installBehavior` `esbonio.server.updateBehavior` `esbonio.server.updateFrequency`	N/A	VSCode only, no longer required.