Skip to content

Installation¤

The information below describes how to install Lexos as a user. If you are interested in contributing to the Lexos source code or documentation, see the separate Development documentation.

Installing Python¤

Lexos requires Python 3.12 or greater. Our development environment is uv, and Lexos should work in a Python virtual environment created using that tool. If you are using a different Python environment, you can install Lexos using pip.

Installing the Lexos Package¤

You can install Lexos using pip:

pip install lexos

If you are using uv, run

uv add lexos

Note

Lexos depends on a pre-release version of the Python puremagic library. In some cases, uv may prevent installation. If you encounter this problem, try uv add lexos --prerelease=allow. If you are using Lexos as a dependency in your project, add the following to your pyproject.toml file:

[tool.uv]
prerelease = "allow"

This will install the Lexos API and all of its dependencies.

By default, uv installs the latest version of Lexos. To update to the latest version with pip, use

pip install -U lexos

Downloading Language Models¤

Many features of Lexos use language models created for the Python spaCy natural language processing library. When you install Lexos, spaCy's multi-language model xx_sent_ud_sm and small English model en_core_web_sm are installed. For information on how Lexos uses language models, see Tokenizing Texts.

Downloading Additional Language Models (Optional)¤

The xx_sent_ud_sm model is a minimal model that can be used for sentence and token segmentation in a variety of languages, while the en_core_web_sm model is specifically for English text. If you are working in another language or need a larger language, you may need to download additional language models. You can find information on available models on the spaCy models page.

To download a model (for instance, the small Chinese model zh_core_web_sm), you can run the following commands in your terminal.

If you are using uv, run:

uv run python -m spacy download zh_core_web_sm

or, if you are not using uv, you can run:

python -m spacy download zh_core_web_sm

Verify Installation¤

To verify that Lexos is installed correctly, you can run the following command in your terminal:

If you are using uv:

uv run python -m lexos --version

or, if you are not using uv:

python -m lexos --version

If you are using a Jupyter notebook, you can also check the installation by running the following code in a cell:

import lexos
print(lexos.__version__)

This should display the version of Lexos that is installed. If you see an error, please check your installation steps or refer to the Troubleshooting section below.

Troubleshooting¤

Below are some common issues and solutions you may encounter during installation:

1. Python Version Error¤

Issue: You see an error like ModuleNotFoundError or SyntaxError when installing or running Lexos.

Solution: Lexos requires Python 3.12 or greater. Check your Python version with:

python --version

If your version is lower than 3.12, please install a compatible version and create a new virtual environment.

2. uv or pip Not Found¤

Issue: The terminal says uv: command not found or pip: command not found.

Solution: Make sure you have installed uv or pip. If not, follow the official installation instructions for your platform.

3. Permission Denied Errors¤

Issue: You see Permission denied when installing packages.

Solution: Always use a virtual environment for Lexos. If you must install globally, you may need to use sudo on Mac and Linux systems, but this is not recommended. Prefer using a virtual environment to avoid permission issues.

4. spaCy Model Not Found¤

Issue: You see an error like OSError: [E050] Can't find model 'en_core_web_sm' or similar when running Lexos features that use spaCy.

Solution: Install the required spaCy model using one of the following commands:

uv run python -m spacy download en_core_web_sm
# or, if not using uv:
python -m spacy download en_core_web_sm

5. Lexos Not Found After Installation¤

Issue: Running python -m lexos --version or import lexos fails with ModuleNotFoundError.

Solution: Ensure you are in the correct virtual environment where Lexos was installed. Activate your environment and try again. If the problem persists, reinstall Lexos using uv add lexos or pip install lexos.

6. Outdated pip or uv¤

Issue: Installation fails with errors about incompatible or missing dependencies.

Solution: Update your package manager:

pip install --upgrade pip
# or
uv pip install --upgrade uv

If you encounter any other problems not covered here, please consider reaching out to the Lexos community Discussion forum on GitHub or checking the GitHub Issues page for assistance.