getButterfly Logo getButterfly code wrangling since 2005

ImagePress Documentation


ImagePress requires WordPress 4.3 or higher in order to function as intended. we recommend the latest version of WordPress. In addition to this, PHP 5.5 is required for certain functions and modules. Check with your host before attempting to install ImagePress.

Minimum requirements
WordPress 4.3+
PHP 5.5+

Recommended requirements
WordPress 4.5+
PHP 5.6+

Optimal requirements
WordPress 4.6+
PHP 7.0+

In addition to the requirements above, ImagePress requires the Permalinks structure to have the post name (/%postname%/) in its structure.

  1. Upload the /imagepress/ folder to your /wp-content/plugins/ directory
  2. Activate the plugin via the Plugins menu in WordPress
  3. A new ImagePress menu will appear in the WordPress menu area

ImagePress works out of the box, but because of its complexity, some settings and options need to be set beforehand.

Your theme needs to have a single-image.php template file and an author template:

    [... other files ...]

The single-image.php allows you to have a customized image template, with custom links and fields. An example template is provided inside the /documentation/ folder. ImagePress will notify you if the template exists in the Installation tab, inside ImagePress options. Note that -image is the actual image post slug, so if your image post slug is poster, you should have a single-poster.php template file.

Template Files for Images

ImagePress is designed to work right out of the box with most WordPress themes. It does this by using a template hierarchy system in the same way WordPress does.

When you create a new image in ImagePress and view the front-end page, chances are it will display just like a single blog post in your theme. That’s because ImagePress will use the single.php template file in your theme to display the image page.

For many themes, that is perfectly fine. For others, not so much. The good news is you’re not stuck with it. You can create a template file used only by ImagePress single images.

ImagePress only uses the single.php template because it can’t find the one it’s looking for: single-image.php. If that template file exists, ImagePress will use it to display single images instead of the template for blog posts.

To create your single-image.php template, copy the single.php from the root of your parent them into the root of your active (child) theme. Then rename the file single-image.php.

Note: This template is now in use for your single image pages. To confirm, make a small edit to that file, save, and view an image page on the frontend of your site to see the change.
Note: To prevent being locked out of your site because of a code error, please consider making the following edits through (S)FTP and a file editor instead of your WordPress dashboard.

The reason you want to copy the template for blog posts is because it gives you a starting point that you can tweak to your needs.

Template Parts

It’s very possible that your WordPress theme uses the get_template_part() function inside of template files for better file organization. This function allows theme developers to take a portion of a template file and place it in another file.

If the single.php file you copied uses get_template_part() to remove part of the single post HTML into another file, your new single-image.php file will do the same. Use the parameters in the function to find which file holds this HTML.

Ex. get_template_part( 'content', 'single' ) refers to content-single.php.

The code in this file (typically just the HTML, not the opening PHP tag at the top of the file) can be copied and pasted in place of the <?php get_template_part(); ?> call from your single-image.php file. That way you have all of the template to play with as you design your single image page.


Collections are used to group two or more (unlimited) images and display them on the user profile page, a dedicated page or, using a shortcode, any page.

Use this shortcode to add it on any page:

[imagepress-collections count="4"]

Use this PHP code to add it as a shortcode:

<?php echo do_shortcode('[imagepress-collections count="4"]'); ?>

Or add this code directly in your theme:

// collections button (optional, can be placed in the sidebar)
Note: In order to view collection images, you need to create a viewer page, which should contain the collections shortcode: [imagepress-show collection="1"].

In order for collections to be visible on any page, they need to have four or more images inside. Collections can be public or private. Private collections are only visible to their author, inside the profile editor.


All the shortcodes and their explanation can be found on the Dashboard tab of your ImagePress plugin. Other undocumented shortcodes can be found below.

[imagepress type="top"]

This shortcode displays the most popular image, based on views and votes. See demo.

[imagepress mode="likes" count="5"]

This shortcode displays the titles of the most liked/voted images. See demo.

[imagepress mode="views" count="5"]

This shortcode displays the titles of the most viewed/visited images. See demo.

[imagepress mode="images" count="6"]

This shortcode displays the most viewed/visited images. See demo.

Field Shortcodes

Custom image fields can be placed anywhere in the sidebar or on the single image template, by using a shortcode. For example, for a Sketchfab field, you would use the slug (“sketchfab” in this case):

<?php echo do_shortcode('[ip-field field="sketchfab"]'); ?>

All shortcodes are displayed for easier copy and paste.

ImagePress Custom Field Shortcode

If you want to migrate all posts or images to ImagePress, you can reuse the custom meta data by matching your old custom meta field name with ImagePress’ new field slug. Note that editing the field title would also change the slug, so make sure you edit the slug last.


ImagePress – How to create a taxonomy template

Frequently Asked Questions

Q: –
A: –


Subscribe to getButterfly Blog

Once a week or so we send an email with our best content. We never bug you, we just send you our latest piece of content.

Love programming?

Learn about the most amazing things. Get smarter everyday!