How to install mxnet for deep learning

When it comes to deep learning, Keras is my favorite Python library…

…but a close runner up is mxnet.

What I like about mxnet is that it combines the best of both worlds in terms of performance and ease of use. Inside mxnet you’ll find:

  • Caffe-like binaries to help you build efficiently packed image datasets/record files.
  • A Keras-like syntax for the Python programming language to easily build deep learning models.
  • Methods to train deep neural networks on multiple GPUs and scale across multiple machines.

Whenever I’m implementing a Convolutional Neural Network I tend to use Keras first. Keras is less verbose than mxnet and is often easier to implement a given neural network architecture + training procedure.

But when it’s time for me to scale up from my initial experiments to ImageNet-size datasets (or larger) I often use mxnet to (1) build an efficiently packed dataset and then (2) train my network on multiple GPUs and/or multiple machines.

Since the Python bindings to mxnet are compiled C/C++ binaries I’m able to milk every last bit of performance out of my machine(s).

In fact, we use mxnet inside Deep Learning for Computer Vision with Python (in particular, the ImageNet Bundle) when training Convolutional Neural Networks on ImageNet and replicating state-of-the-art results for seminal papers, such as VGGNet, ResNet, SqueezeNet, etc..

In the remainder of this blog post you’ll learn how to install and configure mxnet for deep learning on your Ubuntu machine.

How to install mxnet for deep learning

In today’s blog post, I’m going to show you how to get mxnet for deep learning installed on your system in just 5 (relatively) easy steps.

The mxnet deep learning package is an Apache project and comes with great community support. To get started with mxnet I would recommend the tutorials and explanations here. Given the Apache community’s dedication (not to mention, Amazon’s) to mxnet for deep learning, I think it is here to stay for the foreseeable future.

Before we proceed to install mxnet, I’d like to point out that Step #4 is broken into:

  • Step #4a for CPU-only users
  • And Step #4b for GPU users.

The GPU install is by far trickier and there is the potential for error. These instructions have been tested and I’m confident that they will serve as a good guide for you during the installation process.

Let’s get started.

Step #1: Install prerequisites

First, you’ll want to make sure that your Ubuntu 16.04 or 14.04 system is up to date. You can execute the following commands to update packages from the Ubuntu repository:

Next, let’s install some development tools, image/video I/O, GUI operations, and other packages (not all of these are 100% necessary, but you’ll want them installed if you’re doing work in deep learning or machine learning):

Third, let’s install Python header files:

Now that we have the proper system prerequisites installed, let’s move on.

Step #2: Set up a virtual environment

Virtual environments are critical to Python development and are a standard practice. Python virtual environments allow developers to created multiple, isolated development environments on a single machine. You could even use Python virtual environments to install two different versions of a package from the Python Package Index or another source.

I highly encourage you to use virtual environments for deep learning. If you aren’t convinced, then take a look at this RealPython article on why Python virtual environments are a best practice.

For the purposes of the rest of this install guide, we’ll create a Python virtual environment named dl4cv  — this is the name of virtual environment used inside my book, Deep Learning for Computer Vision with Python. I chose the name dl4cv  to keep naming consistent across my books/blog posts. You can use a different name if you so wish.

First we’ll install PIP, a Python package manager. Then we’ll install Python virtual environments and a handy wrapper tool. Subsequently we’ll create a virtual environment and be on our way.

Let’s install pip :

Then we’ll need to pip-install the two Python virtual environment libraries we’ll be using:

Now let’s update our ~/.bashrc  file to include the following lines at the bottom of the file:

Figure 1: Editing your ~/.bashrc file with virtualenvwrapper settings using nano terminal text editor.

Now that ~/.bashrc  has been changed, we need to reload it:

You’ll see a few messages indicating that virtualenvwrapper  has configured itself on your system.

Creating the dl4cv virtual environment

For the purposes of my deep learning book we use Python 3, so let’s create a Python 3 environment on our system named dl4cv . This environment will house relevant packages to deep learning and computer vision, particularly mxnet.

Each time you want to create a new virtual environment, simply supply a name and the Python version you’d like to use. It’s as simple as that. Today we just need the one environment, so let’s move on.

How do I know that I’m in the right environment or in an environment at all?

If you ever deactivate your virtual environment or restart your machine, you’ll need access your Python virtual environment before you resume your work.

To do this, simply use the workon  command:

In this case I’ve supplied the name of my environment, dl4cv , but you would want to specify the name of the environment you desire to work with.

To verify that you’re in the environment you’ll see (dl4cv)  before the bash prompt as is shown in the image below:

Figure 2: Using the workon dl4cv command we can activate the dl4cv virtual environment. Similarly we can use the deactivate command to exit the environment.

To exit your environment, simply deactivate it:

And then you’ll see that the (dl4cv)  has been removed from the beginning of the bash prompt as in Figure 2.

Step #3: Install OpenCV into the dl4cv virtual environment

In this section we will install OpenCV into the dl4cv virtual environment. First we’ll download and unzip OpenCV 3.3. Then we will build and compile OpenCV from source. Finally we will test that OpenCV has been installed.

Install NumPy

First we’ll install NumPy into the virtual environment:

Download OpenCV

Next let’s download opencv and opencv_contrib into your home directory:

You will need to expand the commands above (using the “<=>” button) to copy and past the full path to the  opencv_contrib  URL.

Then, let’s unzip both files:

Running CMake

Let’s create a  build  directory and run CMake:

For CMake, it is important that your flags match mine for compatibility. Also, make sure that your  opencv_contrib  version is identical to the OpenCV version you downloaded (in this case version  3.3.1 ). If the versions do not match then your compile will fail.

Before we move on to the actual compilation step make sure you examine the output of CMake!

Start by scrolling to the section titled  Python 3 .

Make sure that your Python 3 section looks like the figure below:

Figure 3: OpenCV 3.3.1 CMake command results show that the dl4cv virtual environment will be used.

You’ll want to ensure that the Interpreter points to our  python3.5  binary located in the  dl4cv  virtual environment while  numpy  points to our NumPy install.

In either case if you do not see the  dl4cv  virtual environment in these variables’ paths, then it’s almost certainly because you are NOT in the  dl4cv  virtual environment prior to running CMake!

If this is the case, access the  dl4cv  virtual environment using  workon dl4cv  and re-run the command outlined above (I would also suggest deleting the  build  directory, re-creating it, and running CMake again).

Compiling OpenCV

Now we are now ready to compile OpenCV. Assuming that your cmake  command exited without error, ensure you are in the build  directory and execute the following command:

Note: The  -j  flag specifies the number of processor cores to use for the compile. In this case I used  -j4  since my machine has four cores. If you run into compilation errors, you may run the command  make clean  and then just compile without the parallel flag:  make .

From there, all you need to do is to install OpenCV 3.3 and then free up some disk space if you so desire:

Symbolic linking OpenCV to your virtual environment

To sym-link our OpenCV bindings into the  dl4cv  virtual environment, issue the following commands:

Note: Again, make sure you use the “<=>” button in the toolbar above to expand the code block to grab the full ln  command (you don’t want to forget the  file!)

Notice that I am using Python 3.5 in this example. If you are using Python 3.6 (or newer) you’ll want to update the paths above to use your specific Python version.

Secondly, your  .so  file (i.e., the actual OpenCV bindings) may be some variant of what is shown above, so be sure to use the appropriate file by double-checking the path.

Testing your OpenCV 3.3 install

Now that we’ve got OpenCV 3.3 installed and linked, let’s do a quick sanity test to see if things work:

Make sure you are in the  dl4cv  virtual environment before firing up Python ( workon dl4cv ). When you print out the version, it should match the version of OpenCV that you installed (in our case, OpenCV  3.3.1 ).

That’s it — assuming you didn’t encounter an import error, you’re ready to go on to Step #4 where we will install mxnet.

Step #4

Follow the appropriate instructions for your system:

  • Step #4.a: CPU-only mode
  • Step #4.b: GPU mode

Step #4.a: Install mxnet for CPU-only mode

If you have a GPU machine and want to utilize your GPU(s) for deep learning with mxnet, then you should skip this step and proceed to Step #4.b — this section is intended for CPU-only usage.

Let’s clone the mxnet repository and checkout branch 0.11.0  — a branch tested for use with my book, Deep Learning for Computer Vision with Python:

Then we can compile mxnet:

Finally, we need to sym-link mxnet to our dl4cv environment:

Note: Be sure not to delete the mxnet directory in your home folder. Our Python bindings live there and we’ll also need the files in ~/mxnet/bin  for creating serialized image datasets.

Step #4.b: Install mxnet for GPU mode

This step is only for GPU users. If you do not have a GPU on your machine please refer to the CPU-only instructions above.

First, we need to prepare our system to swap out the default drivers with NVIDIA CUDA drivers:

We’re now going to install the CUDA Toolkit. This part of the installation requires that you pay attention to all instructions and beware of system warnings and errors.

First, disable the Nouveau kernel driver by creating a new file:

Then add the following lines to the file, followed by saving + exiting:

Your screen should look like this if you are using nano , but feel free to use oter terminal text editors:

Figure 4: The blacklist_noveau.conf file has been created prior to installing mxnet for deep learning with GPU capability.

Don’t forget this key step where we update the initial RAM filesystem and reboot the machine:

If you are connected via SSH, your session will end and you’ll have to wait a short time before reconnecting.

Install CUDA

Now let’s grab the CUDA Toolkit v8.0 from the NVIDIA CUDA Toolkit website:

You should then select the appropriate download for your system. I’m assuming that you are using Ubuntu 16.04, so your browser should look like this:

Figure 5: Selecting the CUDA 8.0 download for a GPU machine running Ubuntu 16.04.

Notice how I have selected Linux => x86_64 => Ubuntu => 16.04 runfile (local) .

From that screen, download the -run  file which should have a filename of cuda_8.0.61_375.26_linux-run  or similar.

To do this, simply right click to copy the download link and use wget  back in your terminal download the file:

Important: At the time of this writing there is a minor discrepancy on the NVIDIA website. As shown in Figure 5 under the “Base Installer” download, the filename (as is written) ends with .run  . The actual downloadable file ends with -run  . You should be good to go in copying my wget  + URL command for now unless NVIDIA changes the filename again.

Note: You will need to click the “<=>” button in the code block toolbar above to expand the code block. This will enable you to copy the full URL to the -run   file.

From there all you need to do is unpack the -run  file:

Executing the -run  script can take about a minute.

Now let’s install the NVIDIA kernel driver:

You’ll need to follow the prompts on the screen during this step, one of which is to accept the EULA.

Then we can add the NVIDIA loadable kernel module to the Linux kernel:

And finally, install the CUDA toolkit and examples:

You will need to accept licenses and follow prompts again. When it asks you to specify installation paths, you can press <enter> to accept the defaults.

Now that the NVIDIA CUDA driver and tools are installed, let’s update ~/.bashrc  to include the CUDA Toolkit using nano:

Append these lines to the end of the file:

Next, reload the ~/.bashrc  and test the CUDA Toolkit installation by compiling + running the deviceQuery  example program:

From here, if you have a Result = PASS , then we’re ready to install cuDNN.

Install cuDNN

For this step, you will need to Create a free account with NVIDIA and download cuDNN.

For this tutorial be sure to download cuDNN v6.0 for Linux which is what TensorFlow requires (presuming you want to install TensorFlow on your deep learning machine alongside mxnet).

NVIDIA requires authentication to access the download, therefore you won’t be able to use wget  to download the file.

If you’re on a local machine you can simply download the cuDNN archive via your web browser.

However, if you are on a remote machine (i.e., SSH’ing into a machine) you’ll want to first download the file to your local machine and then use  scp  to transfer the file (while replacing username  and your_ip_address  with your appropriate values, of course):

Now that the file is on your remote GPU machine (EC2 in my case), untar the file and then copy the resulting files into  lib64  and  include  respectively, using the  -P  switch to preserve sym-links:

That’s it for installing cuDNN — this step was rather easy so as long as you preserved sym-links, you should be good to go.

Install mxnet with CUDA

Let’s clone the mxnet repository and checkout branch 0.11.0  which has been tested for Deep Learning for Computer Vision with Python:

Then we can compile mxnet:

And finally we need to sym-link mxnet to our dl4cv  environment:

Note: Be sure not to delete the mxnet directory in your home folder. Our Python bindings live there and we’ll also need the files in ~/mxnet/bin  for creating serialized image datasets.

Step #5: Validating install

The last step is to test if mxnet has been properly installed:

Figure 6: Validating our mxnet for deep learning install completed successfully.

If mxnet imports without errors, then congratulations — you have successfully installed mxnet for deep learning.

Where to from here?

Congratulations on getting mxnet installed on your system!

But now that you have mxnet installed, what are the next steps?

How do you…

  • …train your first Convolutional Neural Network?
  • …utilize multiple-GPUs to dramatically reduce training time?
  • …replicate state-of-the-art results from seminal deep learning papers (including ResNet, SqueezeNet, AlexNet, and others) on the challenging ImageNet dataset?

If you’re interested in taking the next step on your journey to deep learning mastery, I’m confident you’d really enjoy my new book, Deep Learning for Computer Vision with Python.

Just click on the link above to take a look.

And while you’re at it, be sure to grab your (FREE) table of contents + sample chapters PDF:

In particular, I recommend you take a look at Chapter 5 of the ImageNet Bundle (one of the free sample chapters) where I demonstrate how to train AlexNet on the ImageNet dataset using mxnet.

In the AlexNet chapter, I:

  1. Provide a thorough discussion of the AlexNet architecture.
  2. Implement the AlexNet architecture from scratch (and explain each line of code ensuring you know exactly what is going on under the hood).
  3. Include detailed experiments discussing how I tune the parameters of AlexNet to achieve higher accuracy experiment after experiment.
  4. Obtain 59.80% rank-1 and 81.75% rank-5 accuracy on ImageNet (which is higher accuracy than current independent papers and publications).

You’ve got nothing to lose — there are no strings attached to the free download of the entire table of contents of my 800+ page book.

To claim your free table of contents + sample chapters, simply head to the Deep Learning for Computer Vision with Python page now.


In today’s blog post you learned how to install mxnet for deep learning on your Ubuntu machine for both CPU only and GPU-based training.

Once you start using mxnet you’ll find that it:

  • Includes Caffe-like binaries to help you build efficiently backed image record files (which will save you a lot of disk space).
  • Provides a Keras-like API to building deep neural networks (although mxnet is certainly more verbose than Keras).

Now that you have your deep learning environment configured, I suggest you take the next step and check out my brand new book, Deep Learning for Computer Vision with Python.

Inside the book you’ll start by learning the fundamentals of deep learning and then graduate to more advanced content, including training networks on the challenging ImageNet dataset from scratch.

You’ll also find my personal blueprint/best practices that I use to determine which deep learning techniques to apply when confronted with a new problem.

To learn more about Deep Learning for Computer Vision with Python, just click here.

Otherwise, be sure to enter your email address in the form below to be notified when new blog posts are published here on PyImageSearch.

, , , , ,

18 Responses to How to install mxnet for deep learning

  1. Hilman November 13, 2017 at 5:21 pm #

    Nice Adrian! Keeps the contents coming!

    • Adrian Rosebrock November 14, 2017 at 5:13 pm #

      Thanks Hilman 🙂

  2. Henric Moberg November 17, 2017 at 4:47 am #

    Thanks Adrian! Just got into this a few days ago and really looking forward to getting started. I was wondering if you could point me in the right direction with something?

    I’m trying the wine detector example from mxnet ( and I get an error when running the script; LocalFileSystem: fail to open “Inception_BN-symbol.json”.

    It might have something to do with the virtualenv but I’m not sure. Any suggestions? If you have time, thanks!

    • Adrian Rosebrock November 18, 2017 at 8:15 am #

      Hi Henric — it sounds like you do not have the “Inception_BN-symbol.json” file on your local computer. Make sure you downloaded the file (this is your network architecture file). You’ll also want to make sure you downloaded the model weights.

      • Henric Moberg November 20, 2017 at 5:11 am #

        Hey! Yeah you are right. I quadruplechecked that the example code was correct but as it turned out the code was looking for Inception-BN and not Inception_BN. Took me ages to find that error. After fixing that underscore the code almost ran fine. I did however have to update to MXNet 0.12 otherwise I got an error about the library unable to updating the symbols.

        After I did that it’s working as it should and now I got it connected to AWS IoT as well. Next step is to start training my own model, should be fun!

        Thanks again for the guide!

        • Adrian Rosebrock November 20, 2017 at 3:49 pm #

          Congrats on resolving the issue, Henric! Nice job.

  3. Pawel April 7, 2018 at 2:22 pm #

    Hi Adrian. Can I use OpenCV 3.4.1?

    • Adrian Rosebrock April 10, 2018 at 12:41 pm #

      I haven’t tried OpenCV 3.4.1 with mxnet but it should work just fine. mxnet is just using OpenCV for some basic image processing operations.

  4. Bezengi April 17, 2018 at 4:07 pm #

    Thanks Adrian! MXNET is a wonderful package. It allows you to visually and quickly form and train your own data set. The package installs quite quickly on both Windows and Ubuntu. I tried installing MXNET on the Raspberry PI 3 B using the tips from “”. The package was compiled and even correctly identifies the version of the package mxnet.__ version__. But then gives an error : “Segmentation fault”. Have you tried working with MXNET on Raspberry PI? Thanks

    • Adrian Rosebrock April 18, 2018 at 3:04 pm #

      Hi Bezengi — I’m sorry to hear about the mxnet issues with the Raspberry Pi. To be honest I have not tried to install mxnet on a Raspberry Pi before. That said, that should not change the error too much. I ran into a weird issue where I needed to first import the “cv2” library before I imported “mxnet”. Try that and see.

  5. Douglas Jones August 6, 2018 at 7:23 pm #

    Awesome as usual but I have one question. After I built mxnet and link the mxnet directory to my virtual env sit-packages I fired up python (3.6.5) and did a import mxnet. I got this warning:

    /home/master/.virtualenvs/dl4cv/lib/python3.6/distutils/ DeprecationWarning: the imp module is deprecated in favour of importlib; see the module’s documentation for alternative uses
    import imp

    I do not know if it is significant but I thought I should ask.


    • Adrian Rosebrock August 7, 2018 at 6:34 am #

      Hey Doug — that’s just a warning. It can be safely ignored.

  6. Aman October 6, 2018 at 2:30 pm #

    I am trying to install mxnet on Raspbian stretch on my RPi 3B+ by using CPU-only approach but everytime I execute the make statement (step 4A) everything gets stuck and cpu usage if Pi goes to 96%, what am I doing wrong?

    • Adrian Rosebrock October 8, 2018 at 9:40 am #

      It sounds like your Raspberry Pi may be (1) locking up or (2) running into a race condition. Try increasing your swap size as I do in this tutorial.

  7. Aman October 6, 2018 at 2:33 pm #

    And when i attempt the step 4b for GPU, it says there are no libraries named like that.

  8. Roberto Sapiain January 23, 2019 at 7:06 am #

    Hi Adrian.

    About the rPi and mxnet. I just saw some days ago (Jan 2019) that there are pip pre-made packages. Are they any good, instead of building them?


    • Adrian Rosebrock January 25, 2019 at 7:27 am #

      I have not tried using mxnet on the Raspberry Pi with the new builds. I have used the pre-built pip-installable mxnet files though — those work well.

  9. Nguyen ANh Nguyen February 14, 2019 at 7:41 am #

    After all opncv, cuda and such are done, you can just:
    pip install mxnet-cu90

    …assumingly you use CUDA 9.0. It will do the job.

Before you leave a comment...

Hey, Adrian here, author of the PyImageSearch blog. I'd love to hear from you, but before you submit a comment, please follow these guidelines:

  1. If you have a question, read the comments first. You should also search this page (i.e., ctrl + f) for keywords related to your question. It's likely that I have already addressed your question in the comments.
  2. If you are copying and pasting code/terminal output, please don't. Reviewing another programmers’ code is a very time consuming and tedious task, and due to the volume of emails and contact requests I receive, I simply cannot do it.
  3. Be respectful of the space. I put a lot of my own personal time into creating these free weekly tutorials. On average, each tutorial takes me 15-20 hours to put together. I love offering these guides to you and I take pride in the content I create. Therefore, I will not approve comments that include large code blocks/terminal output as it destroys the formatting of the page. Kindly be respectful of this space.
  4. Be patient. I receive 200+ comments and emails per day. Due to spam, and my desire to personally answer as many questions as I can, I hand moderate all new comments (typically once per week). I try to answer as many questions as I can, but I'm only one person. Please don't be offended if I cannot get to your question
  5. Do you need priority support? Consider purchasing one of my books and courses. I place customer questions and emails in a separate, special priority queue and answer them first. If you are a customer of mine you will receive a guaranteed response from me. If there's any time left over, I focus on the community at large and attempt to answer as many of those questions as I possibly can.

Thank you for keeping these guidelines in mind before submitting your comment.

Leave a Reply