Skip to content

How to: Setup your own PyPI server

Setting up environment variables

  1. Setting the environment variable MURMUR_INDEX_URL will use the private registry adapter.
export MURMUR_INDEX_URL=http://localhost:8080/simple

Pro Tip

To prevent re-setting the environment variable every time you open a new terminal session, add the above to your .bashrc or .zshrc file.

Set up your PyPI server

Create the following script to start the server.

run_pypi_server.sh
#!/bin/bash

# Use the PYPI_PACKAGES_DIR environment variable or default to ~/packages
PACKAGES_DIR=${PYPI_PACKAGES_DIR:-~/packages}

# Check if the directory exists; if not, create it
if [ ! -d "$PACKAGES_DIR" ]; then
    echo "Creating $PACKAGES_DIR directory..."
    mkdir -p "$PACKAGES_DIR"
else
    echo "$PACKAGES_DIR already exists."
fi

# Define the port, default to 8080 if PYPI_PORT is not set or empty
PORT=${PYPI_PORT:-8080}

# Create ~/.pypirc if it does not already exist and add [pypi] credentials
PYPIRC_PATH=~/.pypirc

if [ ! -f "$PYPIRC_PATH" ]; then
    echo "Creating $PYPIRC_PATH with default credentials..."
    cat <<EOL > "$PYPIRC_PATH"
[pypi]
username = admin
password = admin
EOL
else
    echo "$PYPIRC_PATH already exists."
fi

# Run the docker command
echo "Running the Docker container on port $PORT with data directory $PACKAGES_DIR..."
docker run -p "$PORT":8080 -v "$PACKAGES_DIR:/data/packages" pypiserver/pypiserver:latest run -a . -P .

What does the script do?

  • Defines a packages directory (defaulting to ~/packages) and creates it if missing
  • Sets a port (defaulting to 8080) and writes a default ~/.pypirc if not present
  • Runs the pypiserver Docker container, mapping the directory and port
  • See optional environment variables below for more options

Docker Desktop is required

Docker Desktop is a tool for managing and running containers. Install Docker Desktop on Mac or Windows. Once installed, you can run the following command to start the server.

Run local PyPI server with Docker

With the above script in place, run the following command to start the server.

chmod +x run_pypi_server.sh
./run_pypi_server.sh

Docker Container Running

Docker container is running.

Tip

You can can safely cancel the server by pressing Ctrl+c in the terminal. If you want to start it again, simply hit the play button in Docker Desktop.

Docker Container Running In Browser

Verify the server is running by visiting http://localhost:8080 in your browser.

Docker Container Running In Browser

PyPI server is running.

More options

Optional environment variables
  • PYPI_PORT: The port to run the server on. Defaults to 8080.
  • PYPI_PACKAGES_DIR: The directory where the packages are stored. Defaults to ~/packages.
  • PYPI_USERNAME: The username for the PyPI server. Defaults to admin.
  • PYPI_PASSWORD: The password for the PyPI server. Defaults to admin.
  • MURMUR_EXTRAS_INDEX_URL: The URL of the extras index. Defaults to the public pypi index (for dependencies).

Wrap up