Installing fortls in VS Code: a step-by-step guide
This guide takes you from a clean machine to working Fortran autocompletion, hover and go-to-definition in Visual Studio Code. It covers Python, fortls, VS Code, the Modern Fortran extension, configuration and troubleshooting. If you are new to the idea, start with What is fortls?.
Step 1: Install Python
fortls is a Python package, so you need Python 3 first. Download it from python.org or use your system package manager. On Windows, tick the option to add Python to PATH in the installer. Then check it in a terminal:
python3 --version # Linux / macOS py --version # Windows python3 -m pip --version
Step 2: Install fortls
The simplest way is pip:
python3 -m pip install fortls
If you prefer to keep command-line tools isolated from your other Python packages, pipx install fortls works well too, and conda users can install it from the conda-forge channel. Confirm the installation:
fortls --version fortls --help
If the command is not found, the folder that holds Python scripts is probably not on your PATH; see the troubleshooting section below.
Step 3: Install a compiler (optional, for linting)
fortls provides navigation and completion; compiler errors come from a compiler. To see them as you type, install gfortran (for example sudo apt install gfortran on Debian or Ubuntu, or the GCC package from Homebrew on macOS) or Intel’s ifx. See the resources page for compiler links.
Step 4: Install VS Code and the extension
Download Visual Studio Code. Open the Extensions view (Ctrl+Shift+X), search for Modern Fortran published by fortran-lang, and install it. From a terminal you can run:
code --install-extension fortran-lang.linter-gfortran
The extension integrates fortls for hover, completion, symbols and go-to-definition, and it offers to install fortls with pip if it cannot find it.
Step 5: Open your project
Use File → Open Folder on the root of your Fortran project, then open a .f90 file. Open the Output panel and choose the Modern Fortran channel; you should see fortls start. Hover over a variable or press F12 on a procedure call to test it.
Step 6: Configure
You can pass options to fortls in two ways, and the extension watches both. The first is VS Code’s settings.json (workspace file .vscode/settings.json):
{
"fortran.fortls.path": "fortls",
"fortran.fortls.directories": ["src/**"],
"fortran.linter.compiler": "gfortran",
"fortran.linter.includePaths": ["build/include"]
}
The second is a .fortls file in the project root, which also works in other editors:
{
"source_dirs": ["src/**"],
"excl_paths": ["build"],
"hover_signature": true,
"variable_hover": true
}
Our .fortls generator and VS Code settings generator create these files for you and run entirely in your browser. Set fortran.linter.compiler to ifx, ifort or Disabled if you do not use gfortran.
Troubleshooting
- “fortls not found”. Set
fortran.fortls.pathto the full path of the executable (find it withwhich fortlson Linux and macOS orwhere fortlson Windows), or add the Python scripts folder toPATHand restart VS Code. - Nothing happens or the wrong version runs. You may have two installations, for example one in a virtual environment and one global. Run
fortls --versionin the same terminal VS Code uses and compare it with the version in the Modern Fortran log. - “Module not found in project”. The module’s folder is not indexed. Add it to
source_dirs(orfortran.fortls.directories) and, for external libraries, toext_source_dirsor the include paths. - Slow indexing or high CPU. Exclude build and dependency folders with
excl_paths, and avoid pointingsource_dirsat your whole home directory. - Hover shows too little. Enable
variable_hoverandhover_signaturein your configuration. - Odd results in older code. Check that fixed-form files use a
.fstyle extension and free-form files use.f90, or adjust the suffix options. - Still stuck? Reload the window (Developer: Reload Window), read the Modern Fortran output channel, and search the upstream issue trackers on GitHub.
Conclusion
With Python, fortls and the Modern Fortran extension installed, VS Code becomes a capable Fortran environment. Keep a small .fortls file in each project, exclude build folders, and use the output channel when something misbehaves. Next, try the free configuration tools or download the quick reference.
FORTLS.com is an independent community resource, not the official fortls project. Verify commands against the official documentation for your versions.