Getting started

We’re pleased that you are interested in working on Warehouse.

Your first pull request

After you set up your development environment and ensure you can run the tests and build the documentation (using the instructions in this document), please look at our open issues that are labelled “good first issue”, find one you want to work on, comment on it to say you’re working on it, then submit a pull request. Use our Submitting patches documentation to help.

Setting up a development environment to work on Warehouse should be a straightforward process. If you have any difficulty, please contact us so we can improve the process. You can find us via a GitHub issue, #pypa or #pypa-dev on Freenode, or the pypa-dev mailing list, to ask questions or get involved.

Quickstart for Developers with Docker experience

git clone
cd warehouse
make serve
make initdb

View Warehouse in the browser at http://localhost:80/.

Detailed Installation Instructions

Getting the Warehouse source code

Clone the Warehouse repository from GitHub:

git clone

Configure the development environment

Why Docker?

Docker simplifies development environment set up.

Warehouse uses Docker and Docker Compose to automate setting up a “batteries included” development environment. The Dockerfile and docker-compose.yml files include all the required steps for installing and configuring all the required external services of the development environment.

Installing Docker

The best experience for building Warehouse on Windows 10 is to use the Windows Subsystem for Linux (WSL) in combination with both Docker for Windows and Docker for Linux. Follow the instructions for both platforms, and see Docker and Windows Subsystem for Linux Quirks for extra configuration instructions.

Verifying Docker Installation

Check that Docker is installed: docker -v

Install Docker Compose

Install Docker Compose using the Docker-provided installation instructions.


Docker Compose will be installed by Docker for Mac and Docker for Windows automatically.

Verifying Docker Compose Installation

Check that Docker Compose is installed: docker-compose -v

Building the Warehouse Container

Once you have Docker and Docker Compose installed, run:

make build

in the repository root directory.

This will pull down all of the required docker containers, build Warehouse and run all of the needed services. The Warehouse repository will be mounted inside of the Docker container at /opt/warehouse/src/.

Running the Warehouse Container and Services

You have to start the Docker services that make up the Warehouse application. These need ~4 GB of RAM dedicated to Docker to work. This is more than the default setting of the Docker Engine of 2 GB. Thus, you need to increase the memory allocated to Docker in Docker Preferences (on Mac) or Docker Settings (on Windows) by moving the slider to 4 GB in the GUI.

Then, in one terminal run the command:

make serve

Next, you will:

  • create a new Postgres database,
  • install example data to the Postgres database,
  • run migrations, and
  • load some example data from Test PyPI

In a second terminal, separate from the make serve command above, run:

make initdb

If you get an error about xz, you may need to install the xz utility. This is highly likely on Mac OS X and Windows.


reCaptcha is featured in authentication and registration pages. To enable it, pass RECAPTCHA_SITE_KEY and RECAPTCHA_SECRET_KEY through to serve and debug targets.

Viewing Warehouse in a browser

Once the terminal running the make serve command has logged that a web service has started a reactor:

[twisted.application.runner._runner.Runner#info] Starting reactor...

the web container is listening on port 80. It’s accessible at http://localhost:80/.


If you are using docker-machine on an older version of Mac OS or Windows, the warehouse application might be accessible at https://<docker-ip>:80/ instead. You can get information about the docker container with docker-machine env

Logging in to Warehouse

In the development environment, the password for every account has been set to the string password. You can log in as any account at http://localhost:80/account/login/.

To log in as an admin user, log in as ewdurbin with the password password at http://localhost:80/admin/login/.

Stopping Warehouse and other services

In the terminal where make serve is running, you can use Control-C to gracefully stop all Docker containers, and thus the one running the Warehouse application.

Or, from another terminal, use make stop in the Warehouse repository root; that’ll stop all the Docker processes with warehouse in the name.

What did we just do and what is happening behind the scenes?

The repository is exposed inside of the web container at /opt/warehouse/src/ and Warehouse will automatically reload when it detects any changes made to the code.

The example data located in dev/example.sql.xz is taken from Test PyPI and has been sanitized to remove anything private.

Running your developer environment after initial setup

You won’t have to initialize the database after the first time you do so, and you will rarely have to re-run make build. Ordinarily, to access your developer environment, you’ll:

make serve

View Warehouse in the browser at http://localhost:80/.


Errors when executing make serve

  • If the Dockerfile is edited or new dependencies are added (either by you or a prior pull request), a new container will need to built. A new container can be built by running make build. This should be done before running make serve again.
  • If make serve hangs after a new build, you should stop any running containers and repeat make serve.
  • To run Warehouse behind a proxy set the appropriate proxy settings in the Dockerfile.

“no space left on device” when using docker-compose

docker-compose may leave orphaned volumes during teardown. If you run into the message “no space left on device”, try running the following command (assuming Docker >= 1.9):

docker volume rm $(docker volume ls -qf dangling=true)


This will delete orphaned volumes as well as directories that are not volumes in /var/lib/docker/volumes

(Solution found and further details available at

make initdb is slow or appears to make no progress

This typically occur when Docker is not allocated enough memory to perform the migrations. Try modifying your Docker configuration to allow more RAM for each container and run make initdb again.

Docker and Windows Subsystem for Linux Quirks

Once you have installed Docker for Windows, the Windows Subsystem for Linux, and Docker and Docker Compose in WSL, there are some extra configuration steps to deal with current quirks in WSL. Nick Janetakis has a detailed blog post on these steps, including installation, but this is a summary of the required steps:

1. In WSL, run sudo mkdir /c and sudo mount --bind /mnt/c /c to mount your root drive at /c (or whichever drive you are using). You should clone into this mount and run docker-compose from within it, to ensure that when volumes are linked into the container they can be found by Hyper-V.

2. In Windows, configure Docker to enable “Expose daemon on tcp://localhost:2375 without TLS”. Note that this may expose your machine to certain remote code execution attacks, so use with caution.

3. Add export DOCKER_HOST=tcp:// to your .bashrc file in WSL, and/or run it directly to enable for the current session. Without this, the docker command in WSL will not be able to find the daemon running in Windows.

Building Styles

Styles are written in the scss variant of Sass and compiled using gulp. They will be automatically built when changed when make serve is running.

Running the Interactive Shell

There is an interactive shell available in Warehouse which will automatically configure Warehouse and create a database session and make them available as variables in the interactive shell.

To run the interactive shell, simply run:

make shell

The interactive shell will have the following variables defined in it:

config The Pyramid Configurator object which has already been configured by Warehouse.
db The SQLAlchemy ORM Session object which has already been configured to connect to the database.

You can also run the IPython shell as the interactive shell. To do so export the environment variable WAREHOUSE_IPYTHON_SHELL prior to running the make build step:


Now you will be able to run the make shell command to get the IPython shell.

Running tests and linters


PostgreSQL 9.4 is required because of pgcrypto extension

The Warehouse tests are found in the tests/ directory and are designed to be run using make.

To run all tests, all you have to do is:

make tests

This will run the tests with the supported interpreter as well as all of the additional testing that we require.

If you want to run a specific test, you can use the T variable:

T=tests/unit/i18n/ make tests

You can run linters, programs that check the code, with:

make lint

Building documentation

The Warehouse documentation is stored in the docs/ directory. It is written in reStructured Text and rendered using Sphinx.

Use make to build the documentation. For example:

make docs

The HTML documentation index can now be found at docs/_build/html/index.html.

Building the docs requires Python 3.6. If it is not installed, the make command will give the following error message:

make: python3.6: Command not found
Makefile:53: recipe for target '.state/env/pyvenv.cfg' failed
make: *** [.state/env/pyvenv.cfg] Error 127