Installation¶

Before you begin: install uv if needed¶

PassengerSim is a Python package that is most easily installed in an environment managed by uv. To check if you have uv installed, open a terminal and type uv --version. If you see a version number, you have uv.

If you have uv, but with an outdated version (i.e. less than 0.11), you might be able to update it by running uv self update. If that doesn’t work (it may not, depending on how you originally installed uv), you’ll probably see a hint for the right command to do so.

If you don’t have uv, you can install it by following the instructions on the UV Docs.

Installing PassengerSim¶

If you have received a file named something like install-passengersim-mac-v0.0-20240101.sh, you can use it to install PassengerSim in a uv virtual environment. To do so, open a terminal and navigate to the directory where the file is located. Then, run the following command:

bash install-passengersim-mac-v0.0-20240101.sh

If you use the installation script, it will create a new uv virtual environment named .paxlab and install both PassengerSim and Jupyter Lab into that environment. After the installation is complete, you can start a Jupyter Lab session from the environment by running ./start-paxlab.

Alternatively, you may have received set of wheel files, with the extension “.whl”. You can install these into your Python environment using pip or uv pip. Doing so is just like installing any other Python package using pip, except that you give the filename of the wheel file instead of a package name. For example, if you have a wheel file named passengersim-0.0-py3-none-any.whl, you can install it by running the following command:

uv pip install ./passengersim-0.0-py3-none-any.whl

The “./” at the beginning of the filename is important, as it tells pip or uv to look for the file in the current directory, not on the internet. If you install from wheels, you are responsible for keeping track of which environment you installed into (virtual or otherwise), so you can be sure to activate that environment when you want to use PassengerSim.

Python and SQLite requirements¶

If you install via the provided shell script, the correct Python version and SQLite capabilities will be automatically installed in the virtual environment. If you install via wheel files, you must ensure that the environment you install into has CPython 3.12 or later with a sqlite3 module that supports loadable extensions and the Connection.getconfig and Connection.setconfig methods. PassengerSim needs these capabilities to let its C++ simulation engine share Python’s SQLite connection. Installing the PassengerSim wheel does not add missing features to Python’s SQLite module.

Source-built Python installations, including pyenv builds, may lack extension support. Python’s --enable-loadable-sqlite-extensions build option is disabled by default. Enable it when building Python, and link against a SQLite library that also supports extension loading. With pyenv, pass that option through PYTHON_CONFIGURE_OPTS when installing your chosen Python version. Recreate the virtual environment using the rebuilt interpreter; reinstalling PassengerSim alone cannot fix this requirement.

Run this check with the same Python interpreter you will use for PassengerSim (for example, in a notebook cell or a small Python script):

import sqlite3
from contextlib import closing

with closing(sqlite3.connect(":memory:")) as connection:
    assert callable(getattr(connection, "load_extension", None)), "SQLite extension support is missing"
    flag = sqlite3.SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION
    previous = connection.getconfig(flag)
    try:
        connection.setconfig(flag, True)
        assert connection.getconfig(flag), "SQLite extension loading could not be enabled"
    finally:
        connection.setconfig(flag, previous)
print("SQLite capabilities are available")

An AttributeError, NotSupportedError, or failed assertion indicates an incompatible Python or SQLite build. A security policy can also prevent enabling extensions. This check does not load an extension; after installing PassengerSim, running a small simulation verifies that the compiled bridge can load in your environment. PassengerSim enables extension access only while establishing the connection and restores its previous setting afterward. See Database connections and consolidation for the implementation.