Skip to content

Install CoastSeg with Pixi

Pixi warning (please read)

  1. Keep your local CoastSeg repo up to date, or you will use an outdated CoastSeg.

  2. This is an editable install: Pixi builds CoastSeg from the code in your local git clone (aka the CoastSeg folder).

  3. ⚠️⚠️⚠️Do not run pip install or conda install inside a Pixi environment. It can permanently break the environment.⚠️⚠️⚠️

    • Usually this is fine but if you start getting import errors use the advice below

    • If that happens: delete the .pixi/ folder and re-run pixi shell --locked to reinstall all the dependencies

Table of Contents

Before anything: Install Pixi

Visit the Pixi installation page and follow instructions to install Pixi in your shell.

  1. Clone the CoastSeg Repository

    • You only need to do this once bash git clone --depth 1 https://github.com/SatelliteShorelines/CoastSeg.git

  2. Navigate to the CoastSeg Directory

    • Make sure the directory you are at contains the files. You can use the ls command to list the files.
      • pyproject.toml
      • pixi.lock
    1
2
    cd CoastSeg
# Make sure this folder contains pyproject.toml

  3. Create + activate the Pixi environment

    • This is like conda install + conda activate in one step, it reads CoastSeg’s pixi.lock file to build the environment and then activates it 
      1
      pixi shell

  4. Verify The CoastSeg Environment was Activated

    • You should see something like (coastseg) in your terminal prompt.
    • You can ignore the --frozen in the screenshot below
    • Run the command below to test if CoastSeg is installed in your environment: 
      1
      python -c "import coastseg; print('CoastSeg import OK')"
      pixi default env

  5. Exit the Environment (optional)

    • Exit the current Pixi environment:

    1
    exit
    - Notice how (coastseg) is no longer in front, this means that we have exited the coastseg environment

    exit coastseg pixi

Use Pixi without admin access

If you cannot install Pixi system-wide, install it into a conda environment:

1
2
3
4
5
```
conda create -n coastseg_pixi python=3.11 -y
conda activate coastseg_pixi
conda install -c conda-forge pixi -y
```

Then follow the steps in Basic Pixi install (starting from git clone).

Activate an existing Pixi environment

  • Activate your pixi environment using the pixi shell command

  • Use pixi shell if you want to use the zoo workflow.

    1
2
    cd <coastseg_location>
pixi shell

Upgrade your Pixi environment (get the latest CoastSeg)

❗ Reminder (Pixi installed via conda): If you installed Pixi inside > a conda environment (for example coastseg_pixi), activate that conda environment before running any pixi commands:

1
conda activate coastseg_pixi

  1. Go to your CoastSeg repo

    1
    cd <coastseg_location>
    2. Set the remote connection to CoastSeg on GitHub (if needed)

    • A git remote is a URL pointing to the CoastSeg GitHub repo, used to fetch and pull the latest changes.

    • origin is just the name of that remote — it could be named anything (like cat).

    1
    git remote add origin https://github.com/SatelliteShorelines/CoastSeg.git

    Verify the remote is set up: 

    1
    git remote -v
    You should see something like 
    1
2
    origin  https://github.com/SatelliteShorelines/CoastSeg (fetch)
origin  https://github.com/SatelliteShorelines/CoastSeg (push)
    3. Pull the latest changes

    1
    git pull origin
    If it fails due to local changes: 
    1
2
    git stash
git pull origin
    4. Re-create/update the environment from the updated lockfile

  2. If you get any stange errors about a particular package being incompability try deleting .pixi folder and try this command again

    1
    pixi shell

  3. Verify the upgrade

    1
    python -c "import coastseg; print('CoastSeg import OK')"

Pixi Command Reference Table

Command Description Conda Equivalent Documentation
pixi shell -e <NAME> Activate Pixi environment named <NAME> conda activate <NAME> Pixi shell docs
exit Exit the current Pixi environment conda deactivate Pixi exit docs
pixi install Install dependencies from pyproject.toml and update pixi.lock conda install Pixi install docs
pixi install --frozen Install dependencies strictly from pixi.lock without updating it, even if it differs from pyproject.toml Install from a conda-lock file Pixi frozen install docs

FAQs

Why can't I use pip install or conda install inside my pixi environment?

Pixi is supposed to managed your dependencies and if you run pip install or conda install those packages get written to a different location on your computer than where your pixi environments get saved. This means when you run pixi shell it won't be able to find any of the dependencies you installed with pip install or conda install.

What is pixi.lock?

The pixi.lock file explicitly lists exact versions of Conda and PyPI packages required for each environment defined in pyproject.toml. You can open this file to view detailed package version information and sources (PyPI or Conda Forge).

Wait, what happened to pyproject.toml?

The pyproject.toml file remains mostly unchanged, but now includes additional sections to help Pixi configure your Python environments more effectively.

Hold up, what do you mean there are multiple environments?

Yeah, that confused me too at first. What's special about pixi is that it can define multiple related environments all within the same file, pyproject.toml.

Why did you separate the environments like this?

Great question, I did it because for our zoo workflow we require tensorflow version 2.12 and specific version of the Transformers library to run our models correctly. Unforuately there are not packages avavilable on conda forge for Windows computers. Since we want CoastSeg to be available in on conda-forge I opted to make it an optional dependency and a separate environment. But don't worry you can still the third environment by following the instructions in How to Install the Zoo workflow.