Installation

Mobility uses Python, R, and compiled tools such as osmium-tool.

The recommended installation path uses Pixi. Pixi prepares the tools that Mobility needs in your project folder, then installs Mobility from PyPI as mobility-tools. The Python import name is still mobility.

The mamba installation path is still supported for now. Use it if you already have a working mamba setup or if Pixi is not available on your computer.

1. Install the tools

Install:

• Pixi,
• an editor such as VS Code.

2. Create a Mobility project folder

Create one folder for your first Mobility study. This folder will contain:

• the Pixi environment file,
• your Python scripts,
• optional project notes and output files.

Windows

Open PowerShell and run:

mkdir first-mobility-study
cd first-mobility-study

$version = "v0.2.1"
$base = "https://github.com/mobility-team/mobility/releases/download/$version"
Invoke-WebRequest "$base/pixi.toml" -OutFile "pixi.toml"

pixi install

macOS

mkdir first-mobility-study
cd first-mobility-study

version="v0.2.1"
base="https://github.com/mobility-team/mobility/releases/download/$version"
curl -L -o pixi.toml "$base/pixi.toml"

pixi install

Linux

mkdir first-mobility-study
cd first-mobility-study

version="v0.2.1"
base="https://github.com/mobility-team/mobility/releases/download/$version"
curl -L -o pixi.toml "$base/pixi.toml"

pixi install

3. Check Mobility

Run Python through Pixi from the folder that contains pixi.toml:

pixi run python -c "import mobility; print(mobility.__file__)"

Then run your own script in the same way:

pixi run python my_script.py

The release pixi.toml installs Mobility from PyPI. You do not need a local copy of the Mobility repository when you only want to run a study.

Mamba Fallback

If you already use mamba, you can still create the Mobility environment from the release environment.yml file.

Windows

Open a Miniforge Prompt or PowerShell and run:

$version = "v0.2.1"
$base = "https://github.com/mobility-team/mobility/releases/download/$version"

Invoke-WebRequest "$base/environment.yml" -OutFile "environment.yml"
mamba env create -n mobility -f environment.yml
mamba activate mobility
pip install mobility-tools==0.2.1

macOS

version="v0.2.1"
base="https://github.com/mobility-team/mobility/releases/download/$version"

curl -L -o environment.yml "$base/environment.yml"
mamba env create -n mobility -f environment.yml
mamba activate mobility
pip install mobility-tools==0.2.1

Linux

version="v0.2.1"
base="https://github.com/mobility-team/mobility/releases/download/$version"

curl -L -o environment.yml "$base/environment.yml"
mamba env create -n mobility -f environment.yml
mamba activate mobility
pip install mobility-tools==0.2.1

Check that Python can import Mobility:

python -c "import mobility; print(mobility.__file__)"

Docker

If you use Docker, you can use the Mobility runtime image instead of creating the mamba environment yourself. The container includes Python, R, osmium-tool, and the system libraries needed by Mobility.

From a folder that contains your script, run one of the commands below.

On macOS, Linux, WSL, or Git Bash:

docker run --rm -it \
  -v "$PWD:/app" \
  -w /app \
  ghcr.io/mobility-team/mobility-runtime:0.2.1 \
  python your_script.py

On Windows PowerShell:

docker run --rm -it `
  -v "${PWD}:/app" `
  -w /app `
  ghcr.io/mobility-team/mobility-runtime:0.2.1 `
  python your_script.py

If you cloned the Mobility repository and want to run the French quickstart, replace your_script.py with examples/quickstart-fr.py:

docker run --rm -it \
  -v "$PWD:/app" \
  -w /app \
  ghcr.io/mobility-team/mobility-runtime:0.2.1 \
  python examples/quickstart-fr.py

Use Docker when you want one prepared environment and do not want to manage R packages and system libraries by hand.

4. Choose data folders

Mobility stores downloaded and prepared data on disk. Use two folders:

• one package data folder for shared datasets,
• one project data folder for project-specific inputs and cache files.

You can pass these folders directly:

import mobility

mobility.set_params(
    package_data_folder_path=r"C:\Users\your.name\Documents\mobility-data",
    project_data_folder_path=r"C:\Users\your.name\Documents\mobility-projects\first-project",
)

If you do not pass paths, Mobility uses a default folder in your user directory and asks for confirmation when it has to create it.

For repeated project work, it is usually clearer to store the paths in a .env file and load them in your scripts:

MOBILITY_PACKAGE_DATA_FOLDER=C:\Users\your.name\Documents\mobility-data
MOBILITY_PROJECT_DATA_FOLDER=C:\Users\your.name\Documents\mobility-projects\first-project

5. Install R packages

The first call to mobility.set_params(...) installs the R packages used by Mobility.

This can take time on a new computer. Later runs reuse the installed packages.

Use the default setup first. If a download fails on a company network, see the certificate and proxy notes in Common Problems.

6. Check the installation

Run the quickstart from the documentation:

Quickstart

The first run can be slow because Mobility may download and prepare local data.

You are done when the script finishes without an error and creates a first set of cached project files in your project data folder. If the origin-destination plot opens, your Python, R, data folders, and basic routing setup are working together.

If the command fails before the model starts, first check that you are running Python from the right environment and that mobility.set_params(...) can access your data folders.

With Pixi, run scripts from the folder that contains pixi.toml:

pixi run python your_script.py

With mamba, check that the mobility environment is active.

Editors

You can use Mobility from any editor that points to the Python environment prepared for your project.

VS Code

In VS Code, select the Python interpreter from the Pixi environment in your project folder. It is inside the local .pixi folder.

If you use mamba, select the Python interpreter from the mobility environment. On Windows, it is often located in a folder like:

C:\Users\your.name\AppData\Local\miniforge3\envs\mobility

Common Problems

Pixi cannot download packages on a company network

Use this section only if pixi install fails with a certificate error.

On some company networks, Pixi must be told to use the certificate store from your operating system:

pixi config set tls-root-certs system

Then retry from the folder that contains pixi.toml:

pixi install

This setting affects Pixi itself. It helps Pixi download Python, R, osmium-tool, and Python packages while it prepares the environment.

If the command still fails, your computer may need the company certificate to be installed in the operating system certificate store. Ask your IT team how certificates are managed on your network.

If you use an older Pixi version and system is not accepted, update Pixi first.

Mobility downloads fail with a certificate error

Use this section only if the Pixi or mamba environment is installed, but a Mobility script fails while downloading data.

Some Python downloads may fail on company networks because Python does not use the same certificate store as your browser. In that case, retry the setup with truststore injection:

import mobility

mobility.set_params(
    package_data_folder_path=r"C:\Users\your.name\Documents\mobility-data",
    project_data_folder_path=r"C:\Users\your.name\Documents\mobility-projects\first-project",
    inject_into_ssl=True,
)

This setting affects Python downloads made by Mobility. It does not configure Pixi or mamba.

OSM parsing is very slow on Windows

Make sure the R package osmdata uses the Mobility-provided patched version. On Windows, mobility.set_params(...) installs this version automatically from the installed Python package.

If needed, print the ZIP file path with:

pixi run python -c "from importlib import resources; print(resources.files('mobility.runtime.resources').joinpath('osmdata_0.2.5.005.zip'))"

If you use mamba, run the same Python command inside the active mobility environment.

To check the installed R packages, open R in the same environment and run:

ip = as.data.frame(installed.packages()[, c(1, 3:4)])
ip = ip[is.na(ip$Priority), 1:2, drop = FALSE]
ip

If the osmdata version differs from 0.2.5.005, install the Mobility ZIP manually:

install.packages(file.choose(), repos = NULL)

Then select the printed osmdata_0.2.5.005.zip path.

R package installation fails behind a proxy

Use r_packages_download_method="wininet" in mobility.set_params(...).

If the error continues, you can install the R packages manually.

First open R inside the same environment:

pixi run R

If you use mamba:

mamba activate mobility
R

Then install pak:

install.packages("pak")

If the download still fails on Windows, retry with:

install.packages("pak", method = "wininet")

Exit R with q(), then retry:

import mobility

mobility.set_params(debug=True)

If R still reports missing packages, reopen R and install the main package list with wininet:

install.packages(
    c(
        "remotes", "dodgr", "sf", "dplyr", "sfheaders", "nngeo",
        "data.table", "arrow", "lubridate", "future.apply", "cppRouting",
        "duckdb", "DBI", "jsonlite", "gtfsrouter", "geos", "wk", "FNN",
        "dbscan"
    ),
    method = "wininet"
)

Then install the patched osmdata ZIP as described above.

Mamba cannot download packages on a company network

Pixi has tls-root-certs. Mamba does not use that Pixi setting.

If mamba env create fails with a certificate error, configure certificates in your Miniforge or conda setup. On many installations this means setting ssl_verify to a company certificate PEM file, but the right file and path depend on your computer.

Ask your IT team for the company certificate file if the default mamba setup cannot download packages.

You need help with a new error

Check the open bug reports. If no open issue matches the problem, open a new issue with the command you ran and the full error message.