Yep, I know that setting up a Python environment isn’t technically “installation”, but regardless of what it’s called you’ll need to have this stuff set up properly to use lucy in this course. So here are some instructions to help you out.

Prerequisites

To use lucy you’ll need 2 things:

  • Python - A programming language and what lucy is written in
  • Poetry - A python package manager

In addition to this, if you’re a Windows user then you’ll need to follow the special setup (because Windows). I suggest you read through the prerequisites section and then read through the windows section as there will be specific instructions for installing the prerequisites as well.

Python#

lucy requires Python 3.10 or higher (up to 3.14). If you don’t already have Python installed, then I suggest you just install the latest from the website or whatever package manager you have, as long as it is version >= 3.10. If latest isn’t working then go and complain to the maintainers 😉.

Once you have python installed, you will need to make sure that it is also in your path.

Poetry#

Poetry is the accepted and default way that we manage our python packaging for lucy. If you think you know your way around python versioning and don’t want to use it then by all means, but you’re on your own and I don’t recommend it.

To install Poetry, go to the Poetry docs page install section and following the install instructions for your platform.

Once the install is finished, it will probably give you a filepath to be added to your system path. Make sure you take note of the filepath and follow the path instructions below to get poetry added and working.

Adding to path#

To use python and Poetry, they will need to be added to path. This is something that differs for each system so I suggest you google it and figure it out. Here are some links to help get you started:

If you can close all terminal windows, open a new one and enter the following:

python --version
poetry --version

And neither complain about anything missing and provide sensible outputs, then you have complted the prerequisites step.

Install

Once you have the prerequisites installed and in path, you can move onto the install stage:

Open up a terminal window and navigate to the lucy directory. Then run:

poetry install

and it’ll install all the things.

Assuming the install was successful, you can move on to using lucy.

Windows install#

You have 3 options here

  • Linux style install with WSL
    • Good if you already have WSL installed
  • Natively Windows install using Powershell
    • Good if you don’t know anything about command line and aren’t used to anything like this
  • Give up and use linux
    • Good if you’re a sensible human being who likes developing on platforms that offer the least resistance

The choice is yours, but ultimately the most important thing is that you acknowledge using Windows will increase your headaches by 17%.

Native Windows install#

Python#

Visit the downloads section on the python website, and download the latest version (>= 3.10).

Once downloaded, run the installer with the default options except for the following:

  • Non-Custom
  • Install for all users (checked)
  • Add to PATH (checked)

Check that your install was successful by relaunching powershell and running the following:

python --version

If this prints out the expected version number, then python is installed and in PATH.

If it doesn’t work, then you need to update your path variable to make sure that the correct python folders are present.

By default these should be:

C:\Users\<USER>\AppData\Local\Programs\Python\Python<VERSION>\
C:\Users\<USER>\AppData\Local\Programs\Python\Python<VERSION>\Scripts\

However this may change as Python is updated.

Git for Windows#

If you don’t have it already, then download Git for Windows.

Once downloaded, run the installer with the default options.

Check that your install was successful by relaunching powershell and running the following:

git --version

If this prints out the expected version number, then git is installed and in PATH.

Poetry#

Once you have Python and git installed and verified they’re working, then you can install Poetry.

Follow the instructions in the Poetry section to install poetry, you will be using the native windows install instructions which will look somthing like this:

(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -

NOTE: This is just an example and the actual instruction may have changed, so please use the Poetry website for the latest instructions.

Once the command is finished, there should be a little bit of text in the powershell window with a filepath for you to add to path, by default it should look something like this:

C:\Users\<USER>\AppData\Roaming\Python\Scripts

Copy the filepath, and add it to your system path by following the instructions.

Check that your install was successful and added to path by relaunching powershell and running the following:

poetry --version

If this prints out the a version number, then poetry is installed and in PATH.

lucy#

  1. clone the lucy repo

  2. in a powershell window, navigate to the base lucy directory, should look something like PS X:/path/to/lucy>

  3. install the python dependencies with Poetry using poetry install

With any luck that should be it, but you need to note something:

IMPORTANT

Commands listed in the docs for using lucy are written as if you’re running them on a linux / mac computer. These will NOT work on Windows as written, so you will need to modify them.

Generally, all commands will be written in the following format:

poetry run ./lucy.py <command> [<args>]

To run these same commands on Windows, you will need to translate them to look like the following:

poetry run python lucy.py <command> [<args>]

WSL install#

First you’re going to need the Linux Subsystem for Windows installed, so if you don’t have that then go follow this page and install one.

Once you have done that go ahead and open up a Linux bash shell and run:

  1. sudo apt update followed by sudo apt upgrade

  2. install the pre-reqs with sudo apt install software-properties-common followed by
    sudo apt install zlib1g-dev libncurses5-dev libgdbm-dev libnss3-dev libssl-dev libreadline-dev libffi-dev libreadline-gplv2-dev libncursesw5-dev libsqlite3-dev tk-dev libgdbm-dev libc6-dev libbz2-dev
    Note: If there is a Python 3.10+ in the default apt ppas, you can install this and then skip to 9. You can check this with apt-cache policy python3 or apt-cache policy python3.X (or python3 --version to check the current python3)

  3. cd into /tmp

  4. navigate to https://www.python.org/ftp/python/ and select a python version of 3.10 or later, this will be referred to as ‘VERSION’

  5. download the Python source with sudo wget https://www.python.org/ftp/python/VERSION/Python-VERSION.tgz
    (or whatever the latest version is)

  6. once the download has finished, unzip it with tar xvzf Python-VERSION.tgz

  7. cd into the new Python-VERSION folder

  8. run sudo ./configure --enable-optimizations

  9. run sudo make altinstall

  10. if all went well then python3.X and pip3.X should now be installed, you can check this with python3.X --version and pip3.X --version

  11. we want to set these 2 as our defaults for python and pip, to do so we locate our python3.X and pip3.X with which python3.X and which pip3.X

  12. then we use the outputs of those functions here:
    sudo update-alternatives --install /usr/bin/python python /usr/local/bin/python3.X 2
    and
    sudo update-alternatives --install /usr/bin/pip pip /usr/local/bin/pip3.X 2

  13. we can check that these are indeed our defaults with sudo update-alternatives --config python and sudo update-alternatives --config pip and selecting the 3.X entries if a prompt comes up

  14. install poetry with curl -sSL https://install.python-poetry.org | python3 - (see the Poetry install docs for the latest instructions)

  15. you may get a message saying these (poetry etc.) are not in path, to add them run nano ~/.bash_profile and add the following line: export PATH=$PATH:/the/indicated/path, save the file with ctrl - x -> y -> enter

  16. restart your bash window

  17. by default, Windows is mounted under /mnt/ in the Linux SS, so for example, the folder at G:\example\folder\ is located in the Linux SS as /mnt/g/example/folder/

  18. cd in to a windows directory (under /mnt/) that you want to have the ‘lucy’ folder in and clone it with git

  19. cd in to the ‘lucy’ folder and run poetry install

  20. the pre-reqs will be installed and then afterwards you should be able to run lucy commands with poetry run ./lucy.py <command> (note that Poetry 2.x no longer ships a poetry shell command; if you want an activated shell, use eval $(poetry env activate))

bars search times