Tutorial

Installation

It's recommended to install Mahoraga with uv:

uv tool install -U mahoraga

Server Configuration

Before starting Mahoraga, you need to initialize a directory (for example ~/.mahoraga) to hold its configuration and data:

uvx mahoraga new ~/.mahoraga

uvx pyvim ~/.mahoraga/mahoraga.toml

Server Deployment

Start the server directly to check if your configuration is correct:

cd ~/.mahoraga
uvx mahoraga run

uvx mahoraga run &>/dev/null &

uvw tool run mahoraga run

For better performance, you can set up another server (for example Nginx) in front of Mahoraga. Packages cached on disk can be served within that server, so that subsequent requests won't go to Mahoraga again. In a future version, mahoraga new will generate Nginx configuration files out of the box.

Client Configuration

uv

uv can be configured to grab PyPI packages and Python itself from Mahoraga, via either environment variables or a config file:

export UV_PYTHON_INSTALL_MIRROR=http://127.0.0.1:3450/python-build-standalone
export UV_DEFAULT_INDEX=http://127.0.0.1:3450/pypi/simple
export UV_HTTP_TIMEOUT=60

$Env:UV_PYTHON_INSTALL_MIRROR = "http://127.0.0.1:3450/python-build-standalone"
$Env:UV_DEFAULT_INDEX = "http://127.0.0.1:3450/pypi/simple"
$Env:UV_HTTP_TIMEOUT = "60"

python-install-mirror = "http://127.0.0.1:3450/python-build-standalone"

[[index]]
url = "http://127.0.0.1:3450/pypi/simple"
default = true

[tool.uv]
python-install-mirror = "http://127.0.0.1:3450/python-build-standalone"

[[tool.uv.index]]
url = "http://127.0.0.1:3450/pypi/simple"
default = true

To receive latest Python updates, you should always update uv to latest version. However, uv self update cannot make use of Mahoraga. You can update uv by either uv tool install -U uv or Pixi.

Pixi

Pixi mirror configuration can be done in a single command:

pixi config set -g mirrors '{
    "https://conda.anaconda.org/": ["http://127.0.0.1:3450/conda/"],
    "https://pypi.org/simple/": ["http://127.0.0.1:3450/pypi/simple/"]
}'

pixi config set -g mirrors '{
    "https://conda.anaconda.org/": ["http://127.0.0.1:3450/conda/"],
    "https://pypi.org/simple/": ["http://127.0.0.1:3450/pypi/simple/"],
    "https://raw.githubusercontent.com/prefix-dev/parselmouth/main/files/": ["http://127.0.0.1:3450/parselmouth/"],
    "https://conda-mapping.prefix.dev/": ["http://127.0.0.1:3450/parselmouth/"]
}'

It's recommended to enable sharded repodata in Mahoraga configuration if you use Pixi or rattler-build.
Similar to uv, pixi self-update cannot utilize Mahoraga. Furthermore, pixi global prevents any tool to be exposed as pixi, so you'll need to give it an alias if you update Pixi in this way. Alternatively, pixi exec --force-reinstall pixi works as of now.

rattler-build

rattler-build accepts the same config file format as Pixi. Pass the Pixi config file modified above to rattler-build, unless there are options you would not like to share between Pixi and rattler-build.

rattler-build build \
    --config-file "${PIXI_HOME:-"$HOME/.pixi"}/config.toml" \
    ...

rattler-build build `
    --config-file "$($Env:PIXI_HOME ?? "$HOME/.pixi")/config.toml" `
    ...

pymanager

The next generation of the official Python installer for Windows, pymanager, can be downloaded from Mahoraga:

curl -O http://127.0.0.1:3450/python/pymanager/python-manager-25.0b9.msix

curl -O http://127.0.0.1:3450/python/pymanager/python-manager-25.0b9.msi