Getting started

Requirements

  • an editor or plugin that can launch a language server over standard input and output
  • a Django workspace containing statically declared models

Django itself is not required to run the language server. The server reads Python source without importing the project.

Install the server

The recommended installation uses uv to keep the executable isolated from project dependencies:

uv tool install django-lsp

You can also use pipx install django-lsp or python -m pip install django-lsp. Verify the command is on your path before configuring an editor:

django-lsp --version

Upgrade an existing uv installation with uv tool upgrade django-lsp.

Build from source

Building from source requires Rust 1.95 or newer. From the repository root:

cargo build --release

The resulting executable is target/release/django-lsp.

For a faster development build, use cargo build and point the client at target/debug/django-lsp.

Connect an editor

Configure a Python language-server entry with:

  • command: django-lsp, or the absolute path to the executable if it is not on the editor's path
  • arguments: none
  • transport: standard input and output
  • workspace root: the Django project root

The server writes diagnostics and lifecycle logging to standard error so standard output remains a valid LSP stream.

Visual Studio Code

The first-party Visual Studio Code extension attaches django-lsp to Python files without replacing Pylance, Pyright, Ruff, or another general Python language server. Build and install its universal development package from the repository root:

cd extensions/vscode-extension
npm ci
npm run package:universal
code --install-extension dist/django-lsp-universal.vsix

The universal package uses djangoLsp.server.path when configured, then looks for django-lsp on PATH. Platform-specific release packages additionally contain the matching server executable. Use django-lsp: Restart Django ORM Language Server after changing the executable or project configuration.

In a monorepo or multi-root workspace, the extension starts a client per detected Django project. It searches upward from each opened Python file for manage.py, then pyproject.toml, without leaving the containing workspace folder. Set djangoLsp.workspaceRoot to a relative or absolute path when explicit control is needed.

Zed

The first-party Zed extension attaches django-lsp to Python files without replacing Pyright, Pylsp, Ruff, or another general Python language server. Until the extension is available in Zed's gallery, clone this repository and run zed: install dev extension, selecting extensions/zed-extension.

Enable it alongside the rest of your Python language servers:

{
  "languages": {
    "Python": {
      "language_servers": ["django-lsp", "..."]
    }
  }
}

The "..." entry preserves other registered Python language servers. The extension first checks for django-lsp on PATH; otherwise it downloads the executable matching the current platform from the latest GitHub release.

After the client initializes the server, open a Python file in the workspace and request completion inside a Django filter, exclude, or get call:

Blog.objects.filter(author__te)

The completion list should include paths such as author__team.

Next steps