Fixing img src local file paths
Getting issues with img src not loading local file paths? Check these tips to find how to fix them!
Jan 9, 2023 | Read time 8 minutes🔔 Table of contents
Introduction
A common annoyance that comes up when doing web design locally is loading up local files. For example in the below code, we are trying to load a file located in our C: temp folder - C:/temp/mylocalfile.jpg
<img src="C:/temp/mylocalfile.jpg">Now this does not work because, C:/ is not a protocol. The <img> src attribute only accepts protocols. Now we can see that this will work with older Microsoft browsers such as IE9, but will fail with modern browsers like Chrome, Firefox, etc!
To fix img src to load local file paths, we need to use the file protocol
Using the file protocol
If we want the <img> tag to load up a file within our own computer/machine, we need to use the file protocol (referenced here: https://datatracker.ietf.org/doc/html/rfc8089)
The file protocol follows the syntax:
file://host/path
<img src="file:///C:/Users/weekend/Desktop/snow.jpg" alt="Snow">Keep in mind that we do not need to specify the host part. If there is not host part in the file URI, then it just resolves to localhost.
However, even when we do not set the host value, we still need to specify the extra forward slash file:///....
Img src local path on mac or linux systems
Using the file protocol is a bit different on mac (OSX) or linux systems versus on Windows. Consider the following img tag trying to load a photo.png file:
<img href="file:///~User/photo.png">Notice that we are using the ~ tilde (~User). On mac (OSX) or linux systems, this is a common way to expand our path from the home path. However, the file protocol does not recognize things like the tilde character (~) so you will need to fill it out manually.
So you would need file:///home/User/photo.png (on most Unixes), and use file:///Users/User/photo.png (on Mac OS X)
There are also other things to check if the img src is not loading aswell.
Follow the below suggestions:
Check 1 - Validate the syntax
The syntax for loading a image from a source is by <img src="...">. Now src only accepts valid URLs with accepted protocols. A protocol is a few letters, then a colon and two slashes.
For example, HTTP://, and FTP:// are valid.
Going to back to our orignal code that was not loading the images correctly, <img src="C:/temp/mylocalfile.jpg">, the browser does not recognize that URL, since it is thinking to load http://c:/
When using the file protocol, we need to make sure that we have the correct slashes. file:///.. should be generally safe to use. On windows it is more forgiving and allows double slashes.
Additionally, if your filename contains spaces or special characters we need to encode it.
As an example, lets say we want to reference the file C:/temp/my local file.jpg - notice the spaces. We need to encode it - replacing the whitespace to %20.
<img src="file:///C:/temp/my%20local%20file.jpg">
Note: Why three slashes in
file:///?Using the three slashes
file:///C:/etcis just a short hand. It is the same asfile://localhost/C:/etc
Check 2 - Verify the file extension
One issue that can trip some people up is that the file names can be case insensitive. This will be based on the serve that is hosting your website.
With most Unix based servers (Linux, or OSX), the files are case sensitive. While on Windows servers, they are case insensitive.
As an example, if you are hosting with Apache on Ubuntu it does care about the casing on your filename or path.
As for under Windows it is correct to assume that aBc.html and abc.html are exactly the same file.
In the example below, lets say we have image called photo.png, the second line will not load the image due to the all caps PNG extension
<html>
<body>
<img src="photo.PNG" alt="photo example"> <!-- Will not load (based on server)-->
</body>
</html>Check 3 - Using relative paths
One way to get around issues around local file paths not loading with img src is to use relative paths. However, when we chooe to go down this path, we need to make sure that we are using the correct syntax to load relative files.
Explanation of use of the relative path syntax:
/- This means the root directory../- This means going up on directory./- This means the current directory (if you are working off the current directory, you may not need this - just use the file name)../../- This means going up two directories
Lets say we got the following basic folder structure:
<html>
<body>
<img href="myphoto_A.png"> <!-- Current directory -->
<img href="./myphoto_A.png"> <!-- Current directory -->
<img href="/myphoto_B.png"> <!-- Root directory -->
<img href="../../myphoto_C.png"> <!-- Go up two levels -->
<img href="../myphoto_E.png"> <!-- Go up one level -->
<img href="./custom/myphoto_F.png"> <!-- Start at current directory and go down to the custom folder -->
</body>
</html>Check 4 - Clear cache and check for errors
A common reason why you cant see your PNG src changes is that the browser is caching the image assets.
What I usually do is to open up dev tools (Option + ⌘ + J (on macOS), or Shift + CTRL + J (on Windows/Linux)) and tick the “Disable Cache (while DevTools is open)”
image on how to open DevTools and open its settings. This way we can ensure that our code is using the most up to date image.
Additionally, you can check if your image file (eg PNG or JPG) is loading correctly by inspecting the console in DevTools. Usually if it is not showing, we can see a 404 error:
Tip: Use a development server like Live Server in VS Code!
If you are coding with VS Code, then using the Live Server extension is a must. When you are just coding locally without a local server running, references to images can get a bit confusing.
For example, if you use the root directory / - this could mean your actual C:/ root folder instead of the current folder!
Live server can be downloaded here: https://marketplace.visualstudio.com/items?itemName=ritwickdey.LiveServer
Summary
In this post, I went over some steps you can take to fix issues with loading img src from the local file path. Firstly, we need to make sure that we are using the file protocol (file:///) and that our syntax is correct.
We need to verify that the image path is correct and that we are considering case sensitivity. For windows systems, file paths are case sensitive, while linux or mac OSX are case insensitive.
An alternative to use the file protocol is using relative paths based on your project’s root folder.
Additionally, if the previous steps are not working, we can check to see if the browser is caching the error - in this case we should open up the browser settings (DevTools) to clear the cache!