Fortran Language Server (fortls)

3.2.2 · active · verified Thu Apr 16

fortls is an implementation of the Language Server Protocol (LSP) for Fortran, built with Python 3.7+. It provides rich editor features like code completion, diagnostics, hover information, and symbol navigation for Fortran code. The current version is 3.2.2. It maintains an active development pace with frequent updates and major releases, like v3.0.0 in May 2024, introducing significant changes and new features.

Common errors

```
Error: 'fortls' executable not found.
```
cause The 'fortls' executable is not in the system's PATH environment variable, or the Python environment where it was installed is not active. This is common on Windows or when using virtual environments.

fix Ensure `fortls` is installed in the active Python environment. Add the Python scripts directory (where `fortls.exe` is located) to your system's PATH. Alternatively, configure your editor to explicitly point to the `fortls` executable's full path.
```
LSP feature (e.g., hover, autocompletion) not working or showing incorrect results.
```
cause This can be caused by conflicts with the `fortran-language-server` package, an outdated `fortls` installation, or incorrect project configuration (e.g., missing source directories or preprocessor definitions).

fix First, ensure `fortran-language-server` is uninstalled. If the issue persists, try reinstalling `fortls` (`pip install fortls --upgrade`). Verify your project's `.fortlsrc` configuration file or editor settings (e.g., `source_dirs`, `include_dirs`, `pp_defs`) correctly point to your Fortran source files and necessary preprocessor definitions. Restart your code editor after making changes.
```
fortls initialization never ending / taking too long and consuming excessive resources.
```
cause The language server is likely parsing a very large codebase, potentially with complex or non-standard Fortran, or it may be stuck on a particular file. This can exhaust system memory and CPU.

fix Limit the number of threads `fortls` uses for initialization with the `--nthreads` command-line option. Configure `.fortlsrc` or command-line arguments to exclude unnecessary directories (`--excl_paths`) or file types (`--excl_suffixes`) from being parsed. If possible, identify and isolate the problematic Fortran files or directories.
```
Signature help and hover does not handle elegantly overloaded functions i.e. interfaces.
```
cause This is a known limitation of `fortls` due to the complexity of parsing overloaded functions in Fortran.

fix Currently, there is no direct fix within `fortls` for this specific limitation. Users should refer to the full documentation for overloaded procedures if the basic hover/signature help is insufficient. Keep `fortls` updated, as future releases might improve support.

Warnings

breaking Major release v3.0.0 (May 2024) introduced significant internal changes and new features, potentially affecting configurations or custom integrations that relied on older internal behaviors. Users are advised to review the changelog for detailed updates.
Fix: Review the official fortls documentation and changelog on GitHub for v3.0.0 and subsequent releases. Update editor configurations if necessary. Consider clearing any old configuration files like `.fortlsrc` if encountering issues.
gotcha It is strongly NOT recommended to have both `fortls` and `fortran-language-server` installed simultaneously. They use the same executable name, leading to conflicts and unpredictable behavior.
Fix: Uninstall `fortran-language-server` before installing `fortls` (e.g., `pip uninstall fortran-language-server`). If both are installed, uninstall `fortran-language-server` and then reinstall `fortls` to ensure proper setup.
gotcha On Windows, if `pip` install location is not in your system's PATH, editor integrations (like VS Code) may not find the `fortls.exe` executable.
Fix: Manually add the `pip` scripts directory (e.g., `C:\Users\<username>\AppData\Local\Packages\PythonSoftwareFoundation.Python.<version>\LocalCache\local-packages\Python<version>\Scripts`) to your system's PATH environment variable, or explicitly configure the `fortls` executable path in your editor's settings (e.g., `"fortran.fortls.path": "C:\path\to\fortls.exe"` for VS Code).
gotcha fortls automatically checks PyPI for newer versions and attempts to update itself by default. While this ensures users generally run the latest version, it can be problematic if new versions introduce breaking changes or if a specific version needs to be pinned.
Fix: To disable auto-updating, use the `--disable_autoupdate` command-line option when running `fortls`, or add `"disable_autoupdate": true` to your `.fortlsrc` configuration file.
gotcha For large or complex Fortran projects, `fortls` initialization can take a long time and consume significant system resources (CPU and RAM), potentially leading to editor unresponsiveness or server lag.
Fix: Configure `fortls` with the `--nthreads` option to limit the number of threads used during initialization (default is 4). Exclude unnecessary directories and file types from parsing using `--excl_paths` and `--excl_suffixes` in the command line or `.fortlsrc` configuration file. If possible, upgrade server hardware or test with smaller subsets of the codebase.

Install

pip install fortls PyPI
conda install -c conda-forge fortls Anaconda
brew install fortls Homebrew

Imports

fortls
```
import fortls
```
While 'fortls' is typically run as an executable, it can be imported for programmatic interaction or testing, although this is less common for end-users.

Quickstart

fortls is a language server and is primarily used by code editors that support the Language Server Protocol (LSP). The quickstart demonstrates how to verify the `fortls` executable is installed and accessible. For most users, integration involves installing an editor extension (e.g., 'Modern Fortran' for VS Code) which then manages `fortls` automatically.

# To run fortls as a language server, it's typically launched by a code editor.
# From the command line, you can verify its installation and basic functionality:
# Run the server directly (usually done by an LSP client):
# fortls

# Or check the version:
import subprocess

try:
    result = subprocess.run(['fortls', '--version'], capture_output=True, text=True, check=True)
    print(f"fortls version: {result.stdout.strip()}")
except FileNotFoundError:
    print("Error: 'fortls' executable not found. Ensure it's installed and in your PATH.")
except subprocess.CalledProcessError as e:
    print(f"Error running fortls: {e}\n{e.stderr}")

# To integrate with VS Code, install the 'Modern Fortran' extension.
# It will automatically prompt to install and use fortls.
# For other editors, refer to the 'Editor Integration' section in fortls documentation.

view raw JSON →