Skip to content

Running natively

This page describes the procedure to install and run PrairieLearn fully natively without using Docker. Certain features, such as external graders and workspaces, still require Docker. PrairieLearn supports native execution on macOS, Linux, and Windows inside WSL 2.

Installation

Most of these prerequisites can be installed using the package manager of your OS:

On Ubuntu, use apt for the main prerequisites:

sudo apt install git gcc libc6-dev graphviz libgraphviz-dev redis postgresql-common
# Configure Postgres repository
sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh
sudo apt install postgresql-17 postgresql-17-pgvector
# Optional; needed only for some example questions that use LaTeX
sudo apt install texlive texlive-latex-extra texlive-fonts-extra dvipng

Make sure you start Postgres:

sudo systemctl start postgresql.service

If the command above shows an error like System has not been booted with systemd as init system or Failed to connect to bus, the command above can be replaced with:

sudo service postgresql start

Install uv using the standalone installer:

curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env  # Add uv to PATH for current shell

Node.js 24 is not available in the default Ubuntu repositories -- you can install it through nvm.

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
source ~/.bashrc # or your shell's equivalent
nvm install 24

Enable corepack to make yarn available:

corepack enable

d2 can be installed through the install script:

curl -fsSL https://d2lang.com/install.sh | sh -s --

The pgvector Postgres extension can be installed with the following script:

cd /tmp
git clone --branch v0.8.1 https://github.com/pgvector/pgvector.git
cd pgvector
make
sudo make install

On macOS, ensure you have installed the XCode command line tools:

xcode-select --install

The main prerequisites can be installed with Homebrew:

brew install git graphviz postgresql@17 redis uv d2 node pgvector

# Optional; needed only for some example questions that use LaTeX
brew install texlive

You may want to start up the postgresql server on boot, and add binaries to your path:

brew services start postgresql@17
brew link postgresql@17

Enable corepack to make yarn available:

corepack enable

  • Clone the latest code:

    git clone https://github.com/PrairieLearn/PrairieLearn.git
cd PrairieLearn

  • Install Python dependencies (this will automatically create a virtual environment at .venv if needed):

    make python-deps

  • Install all dependencies and transpile local packages:

    make deps
make e2e-deps

    The above command installs everything. Alternatively, you can run each step individually:

    yarn
make build
make python-deps
make e2e-deps
  • Make sure the postgres database user exists and is a superuser (these might error if the user already exists):
createdb postgres
psql postgres -c "CREATE USER postgres;"
psql postgres -c "ALTER USER postgres WITH SUPERUSER;"

  • Ensure that your local postgres installation allows for local connections to bypass password authentication. First find the authentication configuration file with the command:

    psql postgres -c "SHOW hba_file;"

    The command above will list the path to a file named pg_hba.conf or something equivalent. As either root or the postgres user, edit the file listed by the command above, such that lines that correspond to localhost connections are set up with the trust method (do not change the other lines). If the last two lines already say "trust", no modifications are needed. This will typically be shown as:

    # TYPE  DATABASE        USER            ADDRESS                 METHOD
...
# IPv4 local connections:
host    all             all             127.0.0.1/32            trust
# IPv6 local connections:
host    all             all             ::1/128                 trust

    You may need to restart the PostgreSQL server after changing the file above.

Configuration

If you have your own PrairieLearn course repository, you will need to create the file PrairieLearn/config.json with the path of your local course repository. If you need support for the in-browser file editor or file uploads, you should set filesRoot. If you need support for workspaces, you should provide a path to a directory into which temporary files will be saved. Here is a sample configuration:

config.json
{
  "courseDirs": ["/Users/mwest/git/pl-tam212", "exampleCourse"],
  "filesRoot": "../filesRoot",
  "workspaceHostHomeDirRoot": "/tmp/workspace",
  "workspaceHomeDirRoot": "/tmp/workspace"
}

More information about the config.json can be found in the server configuration documentation.

Development

More information on the development workflow can be found in the development quickstart documentation.