Installation

There are currently three different methods to install Lute v3 on your system, with different system requirements:

I can't recommend any particular installation method: they all have trade offs. My personal preference is to install using pip. If you're studying Japanese and your system supports Docker, I'd recommend using Docker as it the lute3 image includes some other needed dependencies.

Windows users: The instructions below are for Unix/Mac users. Windows installations are similar, but have some challenges, so see Installing on Windows.

Using pip

System requirements:

  • Python 3.8+ and pip. Run python3 --version from the terminal to check.
  • Japanese learners will also need to install MeCab

Lute can be installed from https://pypi.org/project/lute3/. Here's a summary of the instructions from that page for Linux and Mac, Windows will be similar. All of these commands are run from the Terminal.

Create a Lute folder. This can be anywhere on your system.

mkdir -p ~/my_lute
cd ~/my_lute

Set up the virtual environment. If this gives an error, check your Python installation (see "system requirements").

python3 -m venv myenv
source myenv/bin/activate

Install Lute.

pip install --upgrade lute3

Start Lute.

python -m lute.main

# Create a Lute folder
mkdir -p ~/my_lute
cd ~/my_lute

# Set up virtual environment.  If this line gives an error, see "system reqs" above.
python3 -m venv myenv
source myenv/bin/activate

# Install
pip install --upgrade lute3

# Start
python -m lute.main

Now open your web browser to http://localhost:5001. Leave the terminal window open while you're using Lute. When you're done, hit Ctl-C to stop Lute.

You can start lute on a different port if needed:

python -m lute.main --port 9876

Using Docker

System requirements: Docker1

Lute has a pre-built docker image at https://hub.docker.com/r/jzohrab/lute3. There are notes on that page about the image.

Using a docker-compose.yml file:

Create a Lute folder. This can be anywhere on your system.

mkdir -p ~/my_lute_docker
cd ~/my_lute_docker

Create some subfolders (These subfolders will be mounted to the container)

mkdir data
mkdir backups

Create a file named docker-compose.yml in the my_lute folder with the following content:

version: '3.9'
services:
  lute:
    image: jzohrab/lute3:latest
    ports:
      - 5001:5001
    volumes:
      - ./data:/lute_data
      - ./backups:/lute_backup

Run it:

docker compose up

# Create Lute folders
mkdir -p ~/my_lute_docker
cd ~/my_lute_docker
# (These subfolders will be mounted to the container)
mkdir data
mkdir backups

# Docker-compose.yml:
cat > docker-compose.yml <<EOF
version: '3.9'
services:
  lute:
    image: jzohrab/lute3:latest
    ports:
      - 5001:5001
    volumes:
      - ./data:/lute_data
      - ./backups:/lute_backup
EOF

# Run it:
docker compose up

As with the pip installation, you can change the port if your machine is already using port 5001, e.g.:

...
    ports:
      - 9876:5001
...

From source

Developers and gearheads can install Lute from source: see the Lute repository.

If you want to develop Lute, you'll also need to install MeCab.

If you install from source and tinker with the code, make sure you can update later! See Keeping up-to-date when installing from source.

1

Docker is a containerization platform that allows you to run applications in a sandboxed environment (ref the Docker documentation). Docker is not available or is problematic on some systems, particularly Windows.