Skip to content
Go to file

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Docker Stars Docker Pulls Build Status

A small Python Docker image based on Alpine Linux.

Supported tags


  • onbuild images install the requirements.txt of your project from the get go. This allows you to cache your requirements right in the build. Make sure you are in the same directory of your requirements.txt file.


The default docker python images are too big, much larger than they need to be. Hence I built this simple image based on docker-alpine, that has everything needed for the most common python projects - including python-dev (which is not common in most minimal alpine python packages).

jfloff/alpine-python 2.7-slim 60MB
python 2.7-slim 120MB
python 2.7-alpine 61.2MB
jfloff/alpine-python 2.7 235MB
python 2.7 912MB
jfloff/alpine-python 3.6-slim 76.3MB
python 3.6-slim 138MB
python 3.6-alpine 79MB
jfloff/alpine-python 3.6 252MB
python 3.6 922MB
jfloff/alpine-python 3.7-slim 80.4MB
python 3.7-slim 86.7MB
python 3.7-alpine 143MB
jfloff/alpine-python 3.7 256MB
python 3.7 927MB

Perhaps this could be even smaller, but I'm not an Alpine guru. Feel free to post a PR.


  • Installs build-base and python-dev, allowing the use of more advanced packages such as gevent
  • Installs bash allowing interaction with the container
  • Just like the main python docker image, it creates useful symlinks that are expected to exist, e.g. python3 > python, pip2.7 > pip, etc.)
  • Added testing and community repositories to Alpine's /etc/apk/repositories file


This image runs python command on docker run. You can either specify your own command, e.g:

docker run --rm -ti jfloff/alpine-python python

You can also access bash inside the container:

docker run --rm -ti jfloff/alpine-python bash

Usage of onbuild images

These images can be used to bake your dependencies into an image by extending the plain python images. To do so, create a custom Dockerfile like this:

FROM jfloff/alpine-python:3.6-onbuild

# for a flask server
CMD python runserver

Don't forget to build that Dockerfile:

docker build --rm=true -t jfloff/app .

docker run --rm -t jfloff/app

Personally, I build an extended Dockerfile version (like shown above), and mount my specific application inside the container:

docker run --rm -v "$(pwd)":/home/app -w /home/app -p 5000:5000 -ti jfloff/app

Usage of slim images

These images are very small to download, and can install requirements at run-time via flags. The install only happens the first time the container is run, and dependencies can be baked in (see Creating Images).

Via docker run

These images can be run in multiple ways. With no arguments, it will run python interactively:

docker run --rm -ti jfloff/alpine-python:2.7-slim

If you specify a command, they will run that:

docker run --rm -ti jfloff/alpine-python:2.7-slim python

Pip Dependencies

Pip dependencies can be installed by the -p switch, or a requirements.txt file.

If the file is at /requirements.txt it will be automatically read for dependencies. If not, use the -P or -r switch to specify a file.

# This runs interactive Python with 'simplejson' and 'requests' installed
docker run --rm -ti jfloff/alpine-python:2.7-slim -p simplejson -p requests

# Don't forget to add '--' after your dependencies to run a custom command:
docker run --rm -ti jfloff/alpine-python:2.7-slim -p simplejson -p requests -- python

# This accomplishes the same thing by mounting a requirements.txt in:
echo 'simplejson' > requirements.txt
echo 'requests' > requirements.txt
docker run --rm -ti \
  -v requirements.txt:/requirements.txt \
  jfloff/alpine-python:2.7-slim python

# This does too, but with the file somewhere else:
echo 'simplejson requests' > myapp/requirements.txt
docker run --rm -ti \
  -v myapp:/usr/src/app \
  jfloff/alpine-python:2.7-slim \
    -r /usr/src/app/requirements.txt \
    -- python /usr/src/app/

Run-Time Dependencies

Alpine package dependencies can be installed by the -a switch, or an apk-requirements.txt file.

If the file is at /apk-requirements.txt it will be automatically read for dependencies. If not, use the -A switch to specify a file.

You can also try installing some Python modules via this method, but it is possible for Pip to interfere if it detects a version problem.

# Unknown why you'd need to do this, but you can!
docker run --rm -ti jfloff/alpine-python:2.7-slim -a openssl -- python

# This installs libxml2 module faster than via Pip, but then Pip reinstalls it because Ajenti's dependencies make it think it's the wrong version.
docker run --rm -ti jfloff/alpine-python:2.7-slim -a py-libxml2 -p ajenti

Build-Time Dependencies

Build-time Alpine package dependencies (such as compile headers) can be installed by the -b switch, or a build-requirements.txt file. They will be removed after the dependencies are installed to save space.

If the file is at /build-requirements.txt it will be automatically read for dependencies. If not, use the -B switch to specify a file.

build-base, linux-headers and python-dev are always build dependencies, you don't need to include them.

docker run --rm -ti jfloff/alpine-python:2.7-slim \
  -p gevent \
  -p libxml2 \
  -b libxslt-dev \
  -b libxml-dev \
  -- python

Creating Images

Similar to the onbuild images, dependencies can be baked into a new image by using a custom Dockerfile, e.g:

FROM jfloff/alpine-python:2.7-slim
RUN / \
  -p ajenti-panel \
  -p ajenti.plugin.dashboard \
  -p ajenti.plugin.settings \
  -p ajenti.plugin.plugins \
  -b libxml2-dev \
  -b libxslt-dev \
  -b libffi-dev \
  -b openssl-dev \
&& echo
CMD ["ajenti-panel"]
# you won't be able to add more dependencies later though-- see 'Debugging'


The / script that manages dependencies in the slim images creates an empty file, /requirements.installed, telling the script not to install any dependencies after the container's first run. Removing this file will allow the script to work again if it is needed.

You can use the -x flag to see everything the / script is doing.

You can also access bash inside the container:

docker run --rm -ti jfloff/alpine-python:2.7-slim bash

Additional Arguments

-q: silences output from / -x: turns on Bash debugging, making the output very verbose.


These are some of the images that use jfloff/alpine-python as base image. If you have another image that uses this as base image, please submit an issue or PR for it to be added. Image has to be published on Docker Hub.

  • jfloff/alscipy Docker Stars Docker Pulls : image with common packages for Science in Alpine Python.
  • jfloff/pywfm Docker Stars Docker Pulls : image from the python wrapper for Steffen Rendle's factorization machines library libFM.
  • bismuthfoundation/Bismuth-Docker Docker Stars Docker Pulls : node and associated services, from scratch crypto-currency with Python codebase.


Feel free to contribute with whatever you feel like this image is missing. There is also some changes that happen often like, updating Alpine or Python versions. Do not forget that this repo folders mirror Python version and not Alpine versions.


The code in this repository, unless otherwise noted, is MIT licensed. See the LICENSE file in this repository.


A small, more complete, Python Docker image based on Alpine Linux.




No releases published


No packages published
You can’t perform that action at this time.