Tag Archives: NSURL

What is the URL to the Documents Directory in iOS

I keep forgetting this time and time again. There is more than one way to slice a cake:

Option 1

This is how the Apple Templates with Core Data do it. This method takes a file name and returns its URL in the Documents Directory:

Option 2

Here we make use of the foundation function NSHomeDirectory. This method takes a file name and returns its path in the Documents Directory:


If you don’t need to persist files you can make use of the NSTemporaryDirectory. Those files are not backed up and may be cleared by the OS when space is needed. It’s still good practice to delete them yourself if your app no longer needs them here.

How to convert a file path into an NSURL (and back)

To convert a file path into an NSURL:

To create a local path from an NSURL:

NSURLs can also be created directly from an NSString:

If you’re ever tried to pass a local path into this method you’ll have noticed that it doesn’t work. Use the above methods instead.

You can also add path components to a URL, for example to reference your Documents directory:

will give something like

NSURLs have the same method called URLByAppendingPathComponent:

How to download a file and save it to your app's Documents directory

Say you had the URL to a file on the web and you’d like to save said file in the app’s Documents directory. I thought it would be as simple as using the NSFilemanager and copying the URL. But it’s a little more complex than that.

Instead, we can use NSData to retrieve the data and use its method writeToFile to writeToURL. To download the file and turn it into NSData we need an NSURLRequest. We also need a URL to download from, and the location of the user’s Documents directory.

Let’s see how this works:

Note that this method will download the file on the main thread and hence block anything else until it’s finished. Probably not so good for larger downloads. Instead, you can kick it off on another thread using sendAsynchronousRequest:queue:completionHandler.

In your simulator you can check that the file has downloaded, or you can list the Documents directory like so:

How to list the contents of an NSURL

On the iOS simulator we have the luxury of peeking inside our virtual devices with the Finder. We can do this by heading over to the Finder, holding down Option and clicking Go. This will bring up the Library, in which you can navigate to Application Support / iPhone Simulator / 7.0 / Applications / followed by a weird string. One of those will contain your app and all its directories.

But on a real device we’re not so lucky. Has a file really been copied the way we intended it to? NSFileManager to the rescue! Here’s how to read out the contents of a directory at an NSURL:

contentsOfDirectoryAtURL returns an NSArray (of NSURLs) which you can loop through and display any way you like. If you have a file path instead, you can use contentsOfDirectoryAtPath instead.

How to display a UIImage from an NSURL

If you’re displaying images from the main iOS bundle, things are fairly straightforward:

But if you have an NSURL to your image then it’s not as easy. It took me some digging to find out that you have to convert the URL into NSData first, and then display the data:

Convoluted – but currently the only way I know how to do it.

How to copy a file from the Main Bundle into the Documents Directory in iOS

You can do this either by using paths or NSURLs. Apple recommends using NSURLs, so here’s how it works.

In this example we’re copying a file called “Amy.png” which exists in the app’s main bundle.