Want to take your software engineering career to the next level? Join the mailing list for career tips & advice Click here


Torch implementation of neural style algorithm

Star full 4f7b624809470f25b6493d5a7b30d9b9cb905931146e785d67c86ef0c205a402Star full 4f7b624809470f25b6493d5a7b30d9b9cb905931146e785d67c86ef0c205a402Star full 4f7b624809470f25b6493d5a7b30d9b9cb905931146e785d67c86ef0c205a402Star half bd79095782ee4930099175e5ce7f4c89fa3ddabcd56fffcc7c74f6f2a2d46b27Star blank 374f33e4d622a2930833db3cbea26b5d03dc44961a6ecab0b9e13276d97d6682 (1 ratings)
Rated 3.5 out of 5
Subscribe to updates I use neural-style

Statistics on neural-style

Number of watchers on Github 15380
Number of open issues 294
Average time to close an issue 3 days
Main language Lua
Average time to merge a PR 5 days
Open pull requests 29+
Closed pull requests 6+
Last commit about 3 years ago
Repo Created almost 5 years ago
Repo Last Updated over 2 years ago
Size 47.1 MB
Organization / Authorjcjohnson
Page Updated
Do you use neural-style? Leave a review!
View open issues (294)
View neural-style activity
View on github
Fresh, new opensource launches πŸš€πŸš€πŸš€
Software engineers: It's time to get promoted. Starting NOW! Subscribe to my mailing list and I will equip you with tools, tips and actionable advice to grow in your career.
Evaluating neural-style for your project? Score Explanation
Commits Score (?)
Issues & PR Score (?)


This is a torch implementation of the paper A Neural Algorithm of Artistic Style by Leon A. Gatys, Alexander S. Ecker, and Matthias Bethge.

The paper presents an algorithm for combining the content of one image with the style of another image using convolutional neural networks. Here's an example that maps the artistic style of The Starry Night onto a night-time photograph of the Stanford campus:

Applying the style of different images to the same content image gives interesting results. Here we reproduce Figure 2 from the paper, which renders a photograph of the Tubingen in Germany in a variety of styles:

Here are the results of applying the style of various pieces of artwork to this photograph of the golden gate bridge:

Content / Style Tradeoff

The algorithm allows the user to trade-off the relative weight of the style and content reconstruction terms, as shown in this example where we port the style of Picasso's 1907 self-portrait onto Brad Pitt:

Style Scale

By resizing the style image before extracting style features, we can control the types of artistic features that are transfered from the style image; you can control this behavior with the -style_scale flag. Below we see three examples of rendering the Golden Gate Bridge in the style of The Starry Night. From left to right, -style_scale is 2.0, 1.0, and 0.5.

Multiple Style Images

You can use more than one style image to blend multiple artistic styles.

Clockwise from upper left: The Starry Night + The Scream, The Scream + Composition VII, Seated Nude + Composition VII, and Seated Nude + The Starry Night

Style Interpolation

When using multiple style images, you can control the degree to which they are blended:

Transfer style but not color

If you add the flag -original_colors 1 then the output image will retain the colors of the original image; this is similar to the recent blog post by deepart.io.



Optional dependencies:

After installing dependencies, you'll need to run the following script to download the VGG model:

sh models/download_models.sh

This will download the original VGG-19 model. Leon Gatys has graciously provided the modified version of the VGG-19 model that was used in their paper; this will also be downloaded. By default the original VGG-19 model is used.

If you have a smaller memory GPU then using NIN Imagenet model will be better and gives slightly worse yet comparable results. You can get the details on the model from BVLC Caffe ModelZoo and can download the files from NIN-Imagenet Download Link

You can find detailed installation instructions for Ubuntu in the installation guide.


Basic usage:

th neural_style.lua -style_image <image.jpg> -content_image <image.jpg>

OpenCL usage with NIN Model (This requires you download the NIN Imagenet model files as described above):

th neural_style.lua -style_image examples/inputs/picasso_selfport1907.jpg -content_image examples/inputs/brad_pitt.jpg -output_image profile.png -model_file models/nin_imagenet_conv.caffemodel -proto_file models/train_val.prototxt -gpu 0 -backend clnn -num_iterations 1000 -seed 123 -content_layers relu0,relu3,relu7,relu12 -style_layers relu0,relu3,relu7,relu12 -content_weight 10 -style_weight 1000 -image_size 512 -optimizer adam

OpenCL NIN Model Picasso Brad Pitt

To use multiple style images, pass a comma-separated list like this:

-style_image starry_night.jpg,the_scream.jpg.

Note that paths to images should not contain the ~ character to represent your home directory; you should instead use a relative path or a full absolute path.


  • -image_size: Maximum side length (in pixels) of of the generated image. Default is 512.
  • -style_blend_weights: The weight for blending the style of multiple style images, as a comma-separated list, such as -style_blend_weights 3,7. By default all style images are equally weighted.
  • -gpu: Zero-indexed ID of the GPU to use; for CPU mode set -gpu to -1.

Optimization options:

  • -content_weight: How much to weight the content reconstruction term. Default is 5e0.
  • -style_weight: How much to weight the style reconstruction term. Default is 1e2.
  • -tv_weight: Weight of total-variation (TV) regularization; this helps to smooth the image. Default is 1e-3. Set to 0 to disable TV regularization.
  • -num_iterations: Default is 1000.
  • -init: Method for generating the generated image; one of random or image. Default is random which uses a noise initialization as in the paper; image initializes with the content image.
  • -optimizer: The optimization algorithm to use; either lbfgs or adam; default is lbfgs. L-BFGS tends to give better results, but uses more memory. Switching to ADAM will reduce memory usage; when using ADAM you will probably need to play with other parameters to get good results, especially the style weight, content weight, and learning rate; you may also want to normalize gradients when using ADAM.
  • -learning_rate: Learning rate to use with the ADAM optimizer. Default is 1e1.
  • -normalize_gradients: If this flag is present, style and content gradients from each layer will be L1 normalized. Idea from andersbll/neural_artistic_style.

Output options:

  • -output_image: Name of the output image. Default is out.png.
  • -print_iter: Print progress every print_iter iterations. Set to 0 to disable printing.
  • -save_iter: Save the image every save_iter iterations. Set to 0 to disable saving intermediate results.

Layer options:

  • -content_layers: Comma-separated list of layer names to use for content reconstruction. Default is relu4_2.
  • -style_layers: Comma-separated list of layer names to use for style reconstruction. Default is relu1_1,relu2_1,relu3_1,relu4_1,relu5_1.

Other options:

  • -style_scale: Scale at which to extract features from the style image. Default is 1.0.
  • -original_colors: If you set this to 1, then the output image will keep the colors of the content image.
  • -proto_file: Path to the deploy.txt file for the VGG Caffe model.
  • -model_file: Path to the .caffemodel file for the VGG Caffe model. Default is the original VGG-19 model; you can also try the normalized VGG-19 model used in the paper.
  • -pooling: The type of pooling layers to use; one of max or avg. Default is max. The VGG-19 models uses max pooling layers, but the paper mentions that replacing these layers with average pooling layers can improve the results. I haven't been able to get good results using average pooling, but the option is here.
  • -backend: nn, cudnn, or clnn. Default is nn. cudnn requires cudnn.torch and may reduce memory usage. clnn requires cltorch and clnn
  • -cudnn_autotune: When using the cuDNN backend, pass this flag to use the built-in cuDNN autotuner to select the best convolution algorithms for your architecture. This will make the first iteration a bit slower and can take a bit more memory, but may significantly speed up the cuDNN backend.

Frequently Asked Questions

Problem: Generated image has saturation artifacts:

Solution: Update the image packge to the latest version: luarocks install image

Problem: Running without a GPU gives an error message complaining about cutorch not found

Solution: Pass the flag -gpu -1 when running in CPU-only mode

Problem: The program runs out of memory and dies

Solution: Try reducing the image size: -image_size 256 (or lower). Note that different image sizes will likely require non-default values for -style_weight and -content_weight for optimal results. If you are running on a GPU, you can also try running with -backend cudnn to reduce memory usage.

Problem: Get the following error message:

models/VGG_ILSVRC_19_layers_deploy.prototxt.cpu.lua:7: attempt to call method 'ceil' (a nil value)

Solution: Update nn package to the latest version: luarocks install nn

Problem: Get an error message complaining about paths.extname

Solution: Update torch.paths package to the latest version: luarocks install paths

Problem: NIN Imagenet model is not giving good results.

Solution: Make sure the correct -proto_file is selected. Also make sure the correct parameters for -content_layers and -style_layers are set. (See OpenCL usage example above.)

Problem: -backend cudnn is slower than default NN backend

Solution: Add the flag -cudnn_autotune; this will use the built-in cuDNN autotuner to select the best convolution algorithms.

Memory Usage

By default, neural-style uses the nn backend for convolutions and L-BFGS for optimization. These give good results, but can both use a lot of memory. You can reduce memory usage with the following:

  • Use cuDNN: Add the flag -backend cudnn to use the cuDNN backend. This will only work in GPU mode.
  • Use ADAM: Add the flag -optimizer adam to use ADAM instead of L-BFGS. This should significantly reduce memory usage, but may require tuning of other parameters for good results; in particular you should play with the learning rate, content weight, style weight, and also consider using gradient normalization. This should work in both CPU and GPU modes.
  • Reduce image size: If the above tricks are not enough, you can reduce the size of the generated image; pass the flag -image_size 256 to generate an image at half the default size.

With the default settings, neural-style uses about 3.5GB of GPU memory on my system; switching to ADAM and cuDNN reduces the GPU memory footprint to about 1GB.


Speed can vary a lot depending on the backend and the optimizer. Here are some times for running 500 iterations with -image_size=512 on a Maxwell Titan X with different settings:

  • -backend nn -optimizer lbfgs: 62 seconds
  • -backend nn -optimizer adam: 49 seconds
  • -backend cudnn -optimizer lbfgs: 79 seconds
  • -backend cudnn -cudnn_autotune -optimizer lbfgs: 58 seconds
  • -backend cudnn -cudnn_autotune -optimizer adam: 44 seconds
  • -backend clnn -optimizer lbfgs: 169 seconds
  • -backend clnn -optimizer adam: 106 seconds

Here are the same benchmarks on a Pascal Titan X with cuDNN 5.0 on CUDA 8.0 RC:

  • -backend nn -optimizer lbfgs: 43 seconds
  • -backend nn -optimizer adam: 36 seconds
  • -backend cudnn -optimizer lbfgs: 45 seconds
  • -backend cudnn -cudnn_autotune -optimizer lbfgs: 30 seconds
  • -backend cudnn -cudnn_autotune -optimizer adam: 22 seconds

Multi-GPU scaling

You can use multiple GPUs to process images at higher resolutions; different layers of the network will be computed on different GPUs. You can control which GPUs are used with the -gpu flag, and you can control how to split layers across GPUs using the -multigpu_strategy flag.

For example in a server with four GPUs, you can give the flag -gpu 0,1,2,3 to process on GPUs 0, 1, 2, and 3 in that order; by also giving the flag -multigpu_strategy 3,6,12 you indicate that the first two layers should be computed on GPU 0, layers 3 to 5 should be computed on GPU 1, layers 6 to 11 should be computed on GPU 2, and the remaining layers should be computed on GPU 3. You will need to tune the -multigpu_strategy for your setup in order to achieve maximal resolution.

We can achieve very high quality results at high resolution by combining multi-GPU processing with multiscale generation as described in the paper Controlling Perceptual Factors in Neural Style Transfer by Leon A. Gatys, Alexander S. Ecker, Matthias Bethge, Aaron Hertzmann and Eli Shechtman.

Here is a 3620 x 1905 image generated on a server with four Pascal Titan X GPUs:

The script used to generate this image can be found here.

Implementation details

Images are initialized with white noise and optimized using L-BFGS.

We perform style reconstructions using the conv1_1, conv2_1, conv3_1, conv4_1, and conv5_1 layers and content reconstructions using the conv4_2 layer. As in the paper, the five style reconstruction losses have equal weights.


If you find this code useful for your research, please cite:

  author = {Johnson, Justin},
  title = {neural-style},
  year = {2015},
  publisher = {GitHub},
  journal = {GitHub repository},
  howpublished = {\url{https://github.com/jcjohnson/neural-style}},
neural-style open issues Ask a question     (View All Issues)
  • over 3 years choose content layer
  • over 3 years I use it in chinese style.the result is wonderful
  • over 3 years I success the running on the neural-style on MacOSX~
  • over 3 years I don't understand the network architecture.
  • over 3 years What is the neural style network's training output?
  • over 3 years Script to generate larger image
  • over 3 years How to output png?
  • over 3 years There is wrong about running the command nvidia-smi
  • over 3 years "th" command is not working in PHP over browser
  • over 3 years is it possible to work is on windows 10 bash?
  • almost 4 years Runs with no iterations or output?
  • almost 4 years Question about using another trained caffe model
  • almost 4 years Tiling Renders
  • almost 4 years comparing two optimizer, adam, lbfgs
  • almost 4 years torch-cl Error
  • almost 4 years Non-issue: using delta in Gram matrix
  • almost 4 years Function Error
  • almost 4 years Cutorch build error
  • almost 4 years Name of results, number of iterations?
  • almost 4 years " th neural_style.lua " command gives error, No LuaRocks module found for cutorch
  • almost 4 years Comparison of images with neural style result I don't understand
  • almost 4 years test run error : init.lua:654:bad argument #3 to 'new' (number has no integer representation
  • almost 4 years Is there any way just adding the style color without using style
  • almost 4 years Prisma generate neural style offline now
  • almost 4 years uncorrectable ECC error encountered
  • almost 4 years How to install Neural Style on Ubuntu 16.04
  • almost 4 years Is there an implementation for visualising the information each layer contains?
  • almost 4 years why you guys use a net for classification, is there any theory?
  • almost 4 years Tuning style parameters
  • almost 4 years How to start this project?
neural-style open pull requests (View All Pulls)
  • changes to INSTALL.md to include exporting path variables for cuda li…
  • fixed typo
  • Re-seed image if needed
  • build_filename should include the dirname when building the file path for intermediate results
  • Add support for specifying a destination directory
  • adds missing symlink to libfortran
  • add -initial_image option, to continue previous training
  • Add Dockerfile to aid the use of the software
  • "wget" added
  • Docs - Added basic dependencies for begginner
  • Remote misleading sentence regarding ~ from README
  • Torch support (ResNet, Inceptions, etc.), make loadcaffe optional
  • Update INSTALL.md: missed `wget` added
  • Update Install.md
  • Option to initialize image with arbitrary other image
  • Apply filter in docker container, supporting GPU
  • Added the ability to turn off style weight normalization in order to …
  • Adapted torch's new API to fix #179
  • Helper python script (w/ style_layer_weights)
  • Scripts and stuff
  • Update INSTALL.md
  • Added a reflectance padding option from leongatys/NeuralImageSynthesis
  • Use GAN to calculate style loss
  • Update INSTALL.md
  • Update INSTALL.md
  • Fixed misformatted Markdown h1 title
  • Initialize random numbers generator at start
  • Dockerfile with Nvidia support
  • Improve the Adam optimizer's quality
neural-style list of languages used
Other projects in Lua