How to add images to a wordpress theme when working on MAMP?

How to add images to a wordpress theme when working on MAMP?

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

Why Images Fail to Render in WordPress Themes on MAMP

When you are developing a custom WordPress theme on a local environment like MAMP, encountering missing images is a common stumbling block. The frustration often stems from a fundamental misunderstanding of how asset paths work relative to the web server's document root versus your local file system structure. You might be placing an image in wp-content/themes/your-theme/images/logo.png and referencing it with <img src="<?php echo get_stylesheet_directory_uri() . '/images/logo.png'; ?>">, yet the browser simply cannot find it. This isn't a PHP execution error; it is a URL resolution issue specific to how MAMP serves static files.

The core problem usually lies in the distinction between the physical file path and the virtual document root. In a live production environment, your theme's root directory typically sits directly inside the web server's public folder (e.g., /var/www/your-site/wp-content/themes/). However, when running on MAMP, the default document root is often set to htdocs. If you are developing locally, you might have your project structure nested incorrectly or if you are using a specific MAMP configuration where the theme directory is not directly accessible via the standard URI path.

If you reference an image using $theme (which appears to be a typo for get_stylesheet_directory() or similar) inside the PHP tag, you are invoking a server-side function to generate a URL. However, if that function returns a path that points to a directory outside of MAMP's document root, the browser receives a 404 error before it even attempts to render the image. For instance, if your theme is located at /Applications/MAMP/htdocs/blog/wp-content/themes/my-theme, but your code generates a URL that resolves to /my-theme/images/logo.png while MAMP expects files relative to its root, the path will be invalid.

To resolve this, you must ensure your image paths are resolved relative to the WordPress installation, not your local machine's hard drive. The most reliable method is using get_stylesheet_directory_uri(). This function dynamically calculates the URL of your theme's directory based on where WordPress is installed on the server. When used correctly, it ensures that whether you are running on MAMP or a live server, the browser requests the image from the correct location relative to the site root.

Consider this implementation pattern for loading assets:

<img src="<?php echo esc_url( get_stylesheet_directory_uri() . '/images/logo.png' ); ?>" alt="Logo">

This approach is superior to hardcoding paths because it abstracts away the local file system differences. If you have moved your theme folder or changed your MAMP document root, this function automatically adjusts the URL without requiring code changes.

Another potential pitfall involves how MAMP handles file permissions and symbolic links. Even if the path is correct, MAMP may refuse to serve files if they lack read permissions for the web server user (typically www on macOS). You can verify this by checking the file permissions in your terminal:

ls -l htdocs/blog/wp-content/themes/your-theme/images/logo.png

If the output shows restrictive permissions, you may need to adjust them using chmod 644. Additionally, ensure that the image files are not being cached aggressively by your browser or a local development proxy. Clearing your browser cache and disabling any local caching extensions is a necessary step to verify if the new path has taken effect.

Finally, remember that while MAMP is excellent for local development, relying on its default configuration can sometimes mask path issues that would appear in production. If you are planning to deploy this theme later, it is wise to test your asset loading logic in a staging environment that mimics the production directory structure as closely as possible. This ensures that your image paths remain robust regardless of the hosting environment.

Our network