Quick reference

Maintained by: Gurobi Optimization

Where to get help: Gurobi Support, Gurobi Documentation

Supported tags and respective Dockerfile links

• 11.0.3_3.8, 11.0.3, latest Gurobi with Python 3.8
• 11.0.3_3.9 Gurobi with Python 3.9
• 11.0.3_3.10 Gurobi with Python 3.10
• 11.0.3_3.11 Gurobi with Python 3.11
• 11.0.2_3.8, 11.0.2, Gurobi with Python 3.8
• 11.0.2_3.9 Gurobi with Python 3.9
• 11.0.2_3.10 Gurobi with Python 3.10
• 11.0.2_3.11 Gurobi with Python 3.11
• 11.0.1_3.8, 11.0.1 Gurobi with Python 3.8
• 11.0.1_3.9 Gurobi with Python 3.9
• 11.0.1_3.10 Gurobi with Python 3.10
• 11.0.1_3.11 Gurobi with Python 3.11
• 11.0.0_3.8, 11.0.0 Gurobi with Python 3.8
• 11.0.0_3.9 Gurobi with Python 3.9
• 11.0.0_3.10 Gurobi with Python 3.10
• 11.0.0_3.11 Gurobi with Python 3.11
• 10.0.3_3.8, 10.0.3 The latest Gurobi Python image uses Python 3.8, other Gurobi supported python versions and tags are listed below;
• 10.0.3_3.7 Gurobi with Python 3.7
• 10.0.3_3.9 Gurobi with Python 3.9
• 10.0.3_3.10 Gurobi with Python 3.10
• 10.0.2_3.8, 10.0.2 The latest Gurobi Python image uses Python 3.8, other Gurobi supported python versions and tags are listed below;
• 10.0.2_3.7 Gurobi with Python 3.7
• 10.0.2_3.9 Gurobi with Python 3.9
• 10.0.2_3.10 Gurobi with Python 3.10
• 10.0.1_3.8, 10.0.1 Gurobi with Python 3.8
• 10.0.1_3.7 Gurobi with Python 3.7
• 10.0.1_3.9 Gurobi with Python 3.9
• 10.0.1_3.10 Gurobi with Python 3.10
• 10.0.0_3.8, 10.0.0 Gurobi with Python 3.8
• 10.0.0_3.7 Gurobi with Python 3.7
• 10.0.0_3.9 Gurobi with Python 3.9
• 10.0.0_3.10 Gurobi with Python 3.10
• 9.5.2_3.8, 9.5.2 Gurobi with Python 3.8
• 9.5.2_3.7 Gurobi with Python 3.7
• 9.5.2_3.9 Gurobi with Python 3.9
• 9.5.2_3.10 Gurobi with Python 3.10
• 9.5.1, 9.5.1_3.7, 9.5.1_3.9, and 9.5.1_3.10
• 9.5.0

When building a production application, we recommend using an explicit version number instead of the latest tag. This way, you are in control of the upgrade process of your application.

Quick reference (cont.)

Supported architectures: linux/amd64, linux/arm64

Published image artifact details: https://github.com/Gurobi/docker-python

Gurobi images:

• gurobi/optimizer: Gurobi Optimizer (full distribution)
• gurobi/python: Gurobi Optimizer (Python API only)
• gurobi/python-example: Gurobi Optimizer example in Python with a WLS license
• gurobi/modeling-examples: Optimization modeling examples (distributed as Jupyter Notebook)
• gurobi/compute: Gurobi Compute Server
• gurobi/manager: Gurobi Cluster Manager

What is gurobi/python?

The Gurobi Optimizer is the fastest and most powerful mathematical programming solver available for your LP, QP and MIP (MILP, MIQP, and MIQCP) problems. More info at the Gurobi Website.

The Gurobi Optimizer comes with a Python extension module called “gurobipy” that offers convenient object-oriented modeling constructs and an API to all Gurobi features. More info in the Quick Start Guide.

The gurobi/python image provides a base Docker image for applications that use the Gurobi Python interface.

Getting a Gurobi license

This image comes with a Limited License that allows you to solve small optimization problems. To solve larger problems, you will need to get a license that works with your application running in Docker containers. You have a few options:

• The Web License Service (WLS) is a new Gurobi licensing service for containerized environments (Docker, Kubernetes...). Gurobi components can automatically request and renew license tokens to the WLS servers available in several regions worldwide. WLS only requires that your container has access to the Internet. Commercial users can request an evaluation and academic users can request a free license. Please register to access the Web License Manager and read the documentation

• A Gurobi Compute Server allows you to seamlessly offload your optimization computations onto one or more dedicated optimization servers grouped in a cluster. Users and applications can share the servers thanks to advanced queuing and load balancing capabilities. Users can monitor jobs, and administrators can manage the servers. The cluster manager provides additional features and security management. The Compute Server and the Cluster Manager must be installed outside of the Docker cluster.

• The Gurobi Cloud is a simple and cost-effective way to get up and running with powerful Gurobi optimization software running on cloud services. It allows you to launch one or more computers, pre-loaded with Gurobi software and dedicated to you on Microsoft Azure® and Amazon Web Services®.

• A Gurobi Token Server runs on a dedicated machine outside of the Docker cluster. Client programs running in Docker containers can request tokens from the token server.

Note that other standard license types (NODE, Academic) do not work with containers. Please contact your sales representative at [email protected] to discuss licensing options.

Using the client license

If you aren't using the embedded Limited License, you will need to specify a set of properties to connect to a Compute Server cluster, the Gurobi Cloud, or a token server. To do so, you have the following options:

• Mounting the client license file: You can store connection parameters in a client license file (typically called gurobi.lic) and mount it to the container. This option provides a simple approach for testing with Docker. When using Kubernetes, the license file can be stored as a secret and mounted in the container.

• Setting parameters with the API: When your application creates a Gurobi environment, you can specify connection parameters through the API. The parameter values can come from environment variables, a database or from other sources as required by your application.

A quick guide to the appropriate API parameters and license file properties is available here.

We do not recommend adding the license file to the Docker image itself. It is not a flexible solution as you may not reuse the same image with different settings. More importantly, it is not secure as some license files need to contain credentials in the form of API keys that should remain private.

Testing with examples

In the following command-line examples, we will run an example stored on your local machine. The example must be stored in a local directory that will be mounted to the instance.

In the current directory (retrieved using $PWD), create a sub-directory that contains the example you would like to run:

Directory: `$PWD/models`
Content: `poolsearch.py`

See some model examples.

How to use this image?

Building a custom image

This image can be used directly for some tests, but the main goal is to help build applications using the Gurobi Python API. This image can be used as a base image, and specific application dependencies can be added. Here is an example of a Dockerfile:

File Dockerfile

# Indicate the Gurobi reference image
FROM gurobi/python:latest

# Set the application directory
WORKDIR /app

# Install the application dependencies
ADD requirements.txt /app/requirements.txt
RUN pip install -r requirements.txt

# Copy the application code 
ADD . /app

# Command used to start the application
CMD ["python","main.py"]

Once the custom image is built, it can be deployed using Docker, Docker Compose or Kubernetes.

docker build -t my-gurobi-app .

As already mentioned, the license file should not be copied into the image, and we will give example about how to mount the license file in the next sections.

Using Docker

For testing purposes, the following command line starts the gurobi/python container, mounts a directory that contains a few examples, and then runs the example poolsearch.py using the embedded limited license:

$ docker run --volume=$PWD/models:/models \
             gurobi/python  /models/poolsearch.py

... where $PWD is the current directory.

If you need to use a specific license, you can mount the client license file in readonly mode from the local location $PWD:

$ docker run --env=GRB_CLIENT_LOG=3  \
             --volume=$PWD/gurobi.lic:/opt/gurobi/gurobi.lic:ro \
             --volume=$PWD/models:/models:ro \
             gurobi/python  /models/poolsearch.py

Note that this command also enables client logging by using the GRB_CLIENT_LOG variable.

If you have built a custom image, you can apply the same concepts:

$ docker run --env=GRB_CLIENT_LOG=3  \
             --volume=$PWD/gurobi.lic:/opt/gurobi/gurobi.lic:ro \
             my-gurobi-app

Using Docker Compose

Docker Compose can be used if your application requires different components (database, frontend WebUI, backend services...). Docker Compose will help building and connecting these components. For a local test, you can mount the license file as a volume.

Example docker-compose.yml for a Gurobi python instance:

version: '3.7'
services:
  gurobi:
    image: my-gurobi-app
    volumes:
      - ./gurobi.lic:/opt/gurobi/gurobi.lic:ro

Run $ docker-compose up --build to build and run you application.

Using Kubernetes

In a similar way, Kubernetes can be used to deploy your application in a cluster. Here is an example of a deployment descriptor deployment.yaml for an application using the custom image my-gurobi-app:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: optim
  labels:
    name: optim
spec:
  selector:
    matchLabels:
      name: optim
  replicas: 1
  template:
    metadata:
      labels:
        name: optim
    spec:
      volumes:
        - name: gurobi-lic
          secret:
            secretName: gurobi-lic
      containers:
        - name: optim
          image: my-gurobi-app
          imagePullPolicy: IfNotPresent
          volumeMounts:
            - name: gurobi-lic
              mountPath: "/opt/gurobi"
              readOnly: true

Before deploying your application, we recommend storing the license file as a secret and mounting it inside the container.

kubectl create secret generic gurobi-lic --from-file="gurobi.lic=$PWD/gurobi.lic"
kubectl apply -f deployment.yaml

If you are deploying your custom image and using the Cluster Manager within the same cluster, you will need to connect your application to the Cluster Manager. To do so, we recommend the following:

• Create a system user in the Cluster Manager and generate an API key.
• Declare the API key as a secret.

kubectl create secret generic gurobi-manager --from-literal=accessId=xxxxx --from-literal=secret=xxxxxx

• Use environment variables to pass the API key and the manager URL.

          env:
            - name: GRB_CSMANAGER
              value: "http://$(GUROBI_MANAGER_SERVICE_HOST):$(GUROBI_MANAGER_SERVICE_PORT)"
            - name: GRB_CSAPIACCESSID
              valueFrom:
                secretKeyRef:
                  name: gurobi-manager
                  key: accessId
            - name: GRB_CSAPISECRET
              valueFrom:
                secretKeyRef:
                  name: gurobi-manager
                  key: secret

• Finally, in your application, assign the Gurobi environment parameters from the variables, here is an example with Python:

        env = Env(empty=True)
        csManager = os.getenv('GRB_CSMANAGER','')
        if csManager:
            env.setParam('CSManager', csManager)

        csAPIAccessId = os.getenv('GRB_CSAPIACCESSID','')
        if csAPIAccessId:
            env.setParam('CSAPIAccessID', csAPIAccessId)

        csAPISecret = os.getenv('GRB_CSAPISECRET','')
        if csAPISecret:
            env.setParam('CSAPISecret', csAPISecret)

        env.start()

Environment Variables

The following environment variables can be used:

• GRB_CLIENT_LOG: Turns Client Server logging on or off. Options are off (0), only error messages (1), information and error messages (2), or (3) verbose, information, and error messages.

License

By downloading and using this image, you agree with the End-User License Agreement for the Gurobi software contained in this image.

As with all Docker images, these likely also contain other software which may be under other licenses (such as Bash, etc from the base distribution, along with any direct or indirect dependencies of the primary software being contained).

As for any pre-built image usage, it is the image user's responsibility to ensure that any use of this image complies with any relevant licenses for all software contained within.