Running deep dream on Windows and OSX

A few days ago, Google released a Python Notebook to let you play with some of their very recent work on visualisation with neural networks.

Despite being designed to rely on as few dependancies as possible, a recurring complaint I saw is that it's so difficult for non-programmers to set up and start playing with.

If that sounds like you, then you're in luck! I've built and packaged a complete virtual environment, with all dependancies included & ready to go. We can do the entire thing from scratch in a few lines at the terminal (after chewing through a few GB of bandwidth). The tool is called Docker, and the virtual environments are called Containers. What we're going to do is install Docker, pull my deepdream container, and run the container so we can play with the tool in our web-browser.

I'm on a mac, so the guide will follow that. If you're on Linux, you know what to do. If you're on Windows, most things should still work, but you'll need to apply this guide to your environment. I haven't used Windows properly in ~5 years, so I can't provide much help (Boot2docker is available on Windows, so the steps should be extremely similar).

First you'll need Docker - a tool to let you easily use pre-packaged virtual computers on your own computer. To get a good understanding of what we're actually doing, you should read the installation guide. Or if you just want to speed through and get to the cool stuff -

  • Download the boot2docker installer and run it.
  • Open Boot2docker by searching for it in Spotlight (⌘ + space)

You should have something like this now

Second you'll need to get the Docker container somehow. The easiest way to do this is to run docker pull ryankennedyio/deepdream at the terminal we've now got open. This is about 3GB, so go and get a coffee (or three).

Alternatively, you can get the source from Github by downloading as a Zip, extractive, navigating the boot2docker terminal window to that location and executing docker build -t ryankennedy/deepdream . to build the image yourself

Third you need to 'boot' the container. This is done with

docker run -d -p 443:8888 -e "PASSWORD=password" -v /path/to/this/repository:/src ryankennedyio/deepdream

Special note: path/to/this/repository should be the location where you want to play with input images. In my case, that would be /Users/ryankennedy/Pictures. This directory is being shared with the Docker container, so that you can access your input pictures.

Finally enter boot2docker ip at the terminal. Copy and paste it, and enter https://<that-ip-address> into your browser (don't miss the https). You'll get some warnings about an unsafe connection, but that's OK. Enter password when prompted for it.

If we've done everything right until this point, we should now see this.

Click dream.ipynb to start Google's python notebook. You might get Failed to retrieve MathJax from ... popup, but that's OK.

Now what?

Python Notebooks are an interactive way to play with code in a more beginner-friendly manner (I may have just offended the entire scientific Python community with that).

Click on a code block and press the play button at the top. The In[*] on the left indicates that this code block is currently running. When the * turns into a number, the code has finished and you're ready to do the next one.

When you run this code block

img = np.float32('/src/input.jpg'))

the file named input.jpg will be shown. You can edit the code just by double clicking, should you want to change the input image.

If you start getting errors like IOError: [Errno 2] No such file or directory: '/src/input.jpg', then you didn't correctly mount the shared folder to the docker container in the third step. It's important to note that the /path/to/this/repository part in the run command will be shared to the docker container, and the docker container can access this using /src.

The generation may take a little while, but you can see it updating in real time, each iteration over the image.

For an explanation of what's actually happening here, I'd encourage you to read the google research blog post. There's a really nice gallery here, and of course following the #deepdream tag on your choice of poison favourite social network.


No such directory or can’t find folder. Because we’re essentially working in a VM within a VM, (docker inside boot2docker), your host folder needs to be available to boot2docker. By default, only folders inside /Users/ will work, because boot2docker will mount /Users/ when it’s first installed.

For example, on Windows you'd want to do something like //c/Users/me/pictures:/src/ as the parameter to the -v option.

To see what's actually mounted at /src when the VM is running, do the following in boot2docker.

docker ps - then find the 'NAME' of the current container (something weird, like 'insane_babbage' for example).

docker exec -it insane_babbage bash will launch you into terminal inside the container. Once inside, ls /src will show you the contents of the directory that you've mounted. This should give you a clue as to which folder been mounted to the container (if anything).

WebSocket connection failed. Apparently will happen on OSX with Safari. Try with firefox or chrome.

Cannot start container [...] Bind for failed: port is already allocated. You'll be getting this error because you have a program already running on port 443 (the HTTPS default port). The most common case would be that you already have a container running, and you're trying to run another one. Two containers cannot run at the same time, on the same port. Either try to use 4430 instead of 443 (or any number above 1024), or do docker ps and docker stop <container-name>, where <container name> is something like 'insane_babbage'.

Restarting the container. You may deem it necessary to restart the container, if the kernel locks up or the whole app becomes unresponsive. In boot2docker, just stop the container (as explained in the above paragraph) and restart it with the run (step 3) command again.

If all else fails... A lot of the issues I've seen are due to unfamiliarity with Docker. That's expected, since it's a very new tool - and while it has had explosive popularity in the engineering world, it's no surprise that you might not have used it yet. Try to spend 20 minutes running through the introduction tutorials.

Going Further

Different Models. The default 'puppy-slug' model might be boring you by now. Great! I only included the bvlc_googlenet container by default.

You will need to download the models from BVLC's repository. If you go into any of the model folders, there is a link to download the model file (models are not included in the repository). Make sure to download deploy.prototxt from each of those directories too.

Create a new folder for each model you want to play with, and download the .caffemodel and deploy.prototxt into that model's folder. Make sure those folders are inside the shared directory you're mounting, and access them by editing the python block:

model_path = '../caffe/models/bvlc_googlenet/' # substitute your path here
net_fn   = model_path + 'deploy.prototxt'
param_fn = model_path + 'bvlc_googlenet.caffemodel'

to be something like

model_path = '/src/<model-folder-here>/' # substitute your path here
net_fn   = model_path + 'deploy.prototxt'
param_fn = model_path + '<put-model-name-here>.caffemodel'

(Don't miss the '/' on the end of model_path).

Alternative Containers. The team at have produced another container available here. You might need to be a little more comfortable with programming to follow along, but the result is a website running locally, like

comments powered by Disqus