Setting up Sublime Text 4 for Python
Sublime Text has had its first major upgrade since 2017 with Sublime Text 4.
Sublime Text is not an IDE nor it pretends to be, but its powerful plugin system has allowed the community to come up with clever ways to have some IDE capabilities.
I’ve been using ST4 in its beta releases exclusively for some time and arrived at a setup that I enjoy, hopefully you will to.
I will update this post with any developments in the tools and setup.
Disclaimer: This setup will not make ST4 behave like PyCharm or even like VSCode. When you choose ST4 you are sacrificing some IDE features for speed and performance.
The tools
I’ve used Sublime Text for Python since I bought my first ST3 license in 2017. At the time the state-of-the-art way of working in Python was to use Anaconda (not to be confused with Anaconda, the Python distribution). Anaconda still works in ST4 but it’s unfortunately lacking some maintenance and its approach has been superseded by language servers.
Sublime Text does not officially support language servers, however, there is community support via the LSP project allowing plugins to call into different language servers and render results in ST4, and, of course, Python is no exception.
There are two main language servers available for ST4: LSP-pyright , which will perform type checking via Microsoft’s Pyright, and LSP-pylsp , which is based on Python LSP Server.
LSP-pyright , will only perform static typing, while LSP-pylsp has a plugin system that allows calling to other types of tools like linters and formatters like mypy, black, or isort.
Personally, I don’t use Pyright, so I will focus on LSP-pylsp and configuring it with a set of common plugins.
The setup
LSP-pylsp is straight forward to setup as described in its README. Once installed go to the LSP-pylsp preferences and add the following configuration:
"pylsp.plugins.mypy-ls.enabled": true, "pylsp.plugins.flake8.enabled": true, "pylsp.configurationSources": ["flake8"], "pylsp.plugins.pyls_black.enabled": true, > After restarting Sublime Text, open a project and you should see the following:
- Hovering over a symbol should render information about it with links to its definition and references:
- You should see Flake8 and mypy errors as you type by hovering over the warning and error squiggly lines or openin the LSP diagnostics panel with LSP: Toggle Diagnostics Panel :
- Invoke LSP: Format File to format with Black and isort:
- Invoke LSP: Rename to rename a symbol using Jedi
Manual setup
LSP-pylsp installs Python Language Server in ST4’s Package Storage directory with the Python interpreter present in your PATH environment variable. It then proceeds to create a virtual environment and install its dependencies on it.
While this is likely completely fine for most users, you may want more control over the Python version and the versions of the dependencies, potentially ensuring they match the ones in your project. If that’s the case you can setup ST4 and Python LSP Server manually as follows:
- Install LSP using the package manager:
- In your project’s virtual environment (you are using a virtual environment, right?)
pip install python-lsp-server[all] python-lsp-black mypy-ls pyls-isort And any other PyLSP plugins you see fit, these are the ones I use most.
- Go to the Sublime Text preferences, Package Settings, LSP, Settings, to open the general settings for LSP where we will configure some default options for PyLSP and its plugins.
- Add the following:
"clients": "pylsp": "enabled": false, // we will enable PyLSP at the project level "selector": "source.python", "settings": "pylsp.plugins.pyflakes.enabled": false, // enabled by default, use flake8 "pylsp.plugins.pycodestyle.enabled": false, // enabled by default, use flake8 "pylsp.plugins.flake8.enabled": true, // flake8 is included in pyls "pylsp.configurationSources": [ "flake8", // discover flake8 config in ~/.config/flake8, setup.cfg, tox.ini and flake8.cfg ], "pylsp.plugins.jedi_rename.enabled": true, // included in pyls // File formatter, invoke via LSP: Format file "pylsp.plugins.autopep8.enabled": false, // enabled by default, use black "pylsp.plugins.yapf.enabled": false, // enabled by default, use black "pylsp.plugins.black.enabled": true, // from python-lsp-black "pylsp.plugins.mypy_ls.enabled": true, // from mypy-ls >, >, >, > Note that enabled is false in the global LSP settings. This is on purpose to prevent Sublime Text 4 from trying to start an Python LSP Server on all windows. The idea is to only start the server present in each project’s virtual environment separately.
// This section should be present already "folders": [ "path": "", > ], // Add this whole section if not present or just the LSP settings "settings": "LSP": "pylsp": "enabled": true, "command": [ "/bin/pylsp", ], "settings": "pylsp.plugins.flake8.executable": "/bin/flake8", >, >, >, >, > Make sure you replace with the absolute path to your virtual environment.
Troubleshooting
No flake8 linting
If you find things are working but you are not getting flake8 errors, make sure you’ve set up the pylsp.plugins.flake8.executable setting in your project and it’s set to the correct absolute path. If it is not set, or if it is incorrect you will not get errors in Sublime Text but simply no linting information.
Other
If you find some of the plugins are not working or ST4 is showing an error about PyLSP crashing, you may want to add the following lines to the command list in the project’s config:
"command": [ "/bin/pylsp", "--log-file", "", "--verbose" ], The server should restart on each change to the project’s configuration file, but you may need to restart ST4 (luckily it’s lightning fast). You should see the output of PyLSP in that log file which will help you debug any problems. Typical errors include missing dependencies and disabled or incorrect configurations, the logs will include which plugins are active and inactive.
If you find any issues with this setup let me know in this blog’s repo.
Extras
You may also want to install the following Sublime Text packages:
Acknowledgements
I would like to thank the Spyder IDE team for taking the time to fork and maintain Python LSP Server as well as to all the maintainers of the different plugins for PyLSP for adapting to the fork and releasing new versions promptly.
And, of course, the Sublime HQ team for making an awesome text editor.
Updates
- Amend Black plugin to python-lsp-black .
- Disable yapf formatter on LSP general settings as it seems to interfere with Black.
- Added LSP-pylsp as main method of setup.
- Amend incorrect statement that LSP is officially supported by Sublime Text when it’s a community project.
- Remove troubleshooting “index out of range” section which was fixed recently in LSP.
Sublime text python linux
Plugins in Sublime Text are Python files located in the root of a package . The following document describes the Python environment the plugins are run in.
Overview🔗
Sublime Text runs plugins in a separate process from the main editor UI. This process runs an executable named plugin_host .
Running plugins in a separate process ensures the entire editor will not crash due to a poorly written plugin. If a plugin does cause the plugin_host to crash, a user may still save their work before re-starting Sublime Text.
All plugins are run in a single plugin_host process, and share a single Python environment. Each plugin is loaded as a sub-module of a module named after the package. For example, a plugin in the file MyPackage/my_plugin.py will be loaded as the Python module MyPackage.my_plugin .
The plugin_host process contains an embedded version of the Python programming language, and exposes an API to plugins. The plugin_host executable always uses its own embedded version of Python, even if the end-user has Python installed on their machine.
Python Version🔗
By default all plugins are run using Python 3.3.6, except inside the User package which always uses the latest python. Sublime Text‘s build of Python 3.3.6 includes a handful of patches backported from Python 3.4 to fix issues with unicode paths and crashes with the ctypes module on 64bit versions of Windows.
Starting in build 4050, plugins may also be run using Python 3.8. Python 3.8 features many improvements to the language, better performance and continued support and bug fixes from the Python Software Foundtion.
Selecting the Python Version🔗
To provide for backward compatibility, Sublime Text 4050 will continue to run all plugins using Python 3.3.
Any package that wishes to use Python 3.8 must create a file named .python-version in the root of the packages. This file should contain either the text 3.3 or 3.8 to select the version of Python to use. If a file named .python-version is not present, or it contains any value other than 3.8 , then Python 3.3 will be used.
All plugins in a package will use the same version of Python. Any package with a .python-version file containing 3.8 loaded in older builds of Sublime Text will try to run the plugins using Python 3.3.
Modules🔗
The Python environment within plugin_host contains all of the modules in The Python Standard Library, except for:
Pre-Installed Packages🔗
The following the packages are pre-installed in both the Python 3.3 and 3.8 environments: