Skip to content
Get packs

Guide · Open source

How to use neural-style: install Torch and transfer artistic styles

Updated · written with AI from the project's own documentation and checked against our catalogue data

neural-style is an open-source Torch implementation of the 2015 paper A Neural Algorithm of Artistic Style by Gatys, Ecker and Bethge. It takes a content photo and a style image, such as a painting, and produces a new image that keeps the content of the first while adopting the style of the second. This guide is for people who are comfortable installing developer tools and want to set it up, understand its main options and know when it fits their needs.

neural-stylejcjohnson/neural-style · ★ 18.3k · MIT

Quick start

  1. 1Install Torch7 and loadcaffe. Set up the required Torch7 framework and the loadcaffe package before anything else.
  2. 2Add optional GPU backends if needed. Install CUDA with cunn, cudnn.torch, or cltorch and clnn if you want a GPU backend.
  3. 3Clone the repository. Get the jcjohnson/neural-style code from GitHub onto your machine.
  4. 4Download the VGG model. Run sh models/download_models.sh from the project folder to fetch the VGG-19 network.
  5. 5Pick your content and style images. Choose a photo as the content image and a painting or artwork as the style image.
  6. 6Adjust style and content flags. Use -style_scale, the content/style weights and -original_colors 1 to shape the result.

What neural-style does

The algorithm uses convolutional neural networks to combine the content of one image with the artistic style of another. You supply a content image, such as a photograph, and one or more style images, such as paintings. The output keeps the subject of the photo while taking on the look of the artwork.

The project is written in Lua and built on the Torch framework. It is an implementation of the paper, so it is a good fit for reproducing its results.

Install the dependencies

You need Torch7 and loadcaffe. Other backends are optional: CUDA with cunn, cuDNN via cudnn.torch, or OpenCL via cltorch and clnn. The README lists CUDA 6.5 or later as the requirement for the CUDA backend.

Setup is a clone-and-build process, so expect to install Torch and its packages before anything runs.

  • Required: torch7 and loadcaffe
  • Optional CUDA backend: CUDA 6.5+ and cunn
  • Optional cuDNN backend: cudnn.torch
  • Optional OpenCL backend: cltorch and clnn

Download the VGG model

After the dependencies are installed, run the provided script to download the VGG model. The README says this downloads the original VGG-19 network.

sh models/download_models.sh

Choose a style and content weight

The algorithm lets you trade off the relative weight of the style and content reconstruction terms. The README shows the same Picasso self-portrait applied to a photo at several content-to-style settings, so you can see how the balance changes the output.

The -style_scale flag controls the size of the style image before style features are extracted. The README shows scale values of 2.0, 1.0 and 0.5 producing different types of artistic features.

  • -style_scale: resize the style image before feature extraction (examples use 2.0, 1.0 and 0.5)
  • Content/style weight: lower the content weight to push the output further toward the style
-style_scale 1.0

Blend multiple style images

You can pass more than one style image to blend artistic styles. The README also describes style interpolation, which controls how strongly each style contributes when several are used. Examples in the README pair The Starry Night with The Scream and Seated Nude with Composition VII.

Keep the original colours

Adding the flag -original_colors 1 makes the output keep the colours of the content image, so only the style texture is transferred. The README notes this is similar to a colour-independent style transfer approach described by deepart.io.

-original_colors 1

What people use it for

  • Rendering a photo of a city or landscape in the style of a famous painting, as shown with the Golden Gate Bridge examples.
  • Reproducing Figure 2 from the Gatys et al. paper with the Tubingen photograph.
  • Blending two styles, such as The Scream and Composition VII, into one image.
  • Keeping a portrait's colours while applying the texture of an artwork.
  • Studying how the content and style weights change the balance of an output image.

Frequently asked questions

Is neural-style free to use?

neural-style is released under the MIT licence, according to the project's listing. The MIT licence generally permits use, modification and redistribution, so check the licence file in the repository for the exact terms.

How do I install neural-style?

Install Torch7 and loadcaffe, then clone the repository. After the dependencies are in place, run sh models/download_models.sh to download the VGG model.

What do I need to run neural-style?

You need Torch7 and loadcaffe as required dependencies. CUDA 6.5+ with cunn, cudnn.torch, or cltorch with clnn are optional backends for GPU acceleration.

Does neural-style work without a GPU?

The README mentions CUDA, cuDNN and OpenCL backends but does not describe CPU performance in the text provided. Expect the GPU backends to be the ones the project documents.

Is there a simpler alternative to neural-style?

If you want a point-and-click app or a modern Python workflow, look at comparable projects such as Fast Neural Style, neural-style-pt, or Magenta arbitrary image stylization. This project is a Torch and Lua codebase and needs a setup process.

Can I use more than one style image?

Yes. The README says you can use more than one style image to blend multiple artistic styles, and style interpolation controls how strongly they blend.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

neural-style suits researchers and students reproducing the Gatys et al. paper, and developers who want to work in Torch. If you want a simple app or a PyTorch-based workflow, a comparable project such as neural-style-pt or Magenta arbitrary image stylization will likely be a better fit.

Install options & downloads