Skip to main content
All CollectionsGeneral
How to upload a large folder by running a local IPFS node
How to upload a large folder by running a local IPFS node

A step-by-step guide on how to transfer content to us over the IPFS network.

Matt Ober avatar
Written by Matt Ober
Updated over a week ago

⚠️ The maximum size for a file or folder is 25GB, and while this method can be used to upload a folder of that size and sometimes larger, Pinata cannot guarantee it's success. ⚠️

Web transfers of extremely large directories can often fail for a variety of reasons. This guide will walk you through step by step instructions on how to get your folder of content uploaded to Pinata by transferring it directly from your local computer to us over the IPFS network. How cool is that?

There are two approaches you can take, either the simpler IPFS Desktop app or using the more technical CLI approach. Both are equally effective!

IPFS Desktop

1. Install IPFS Desktop

You can download the IPFS Desktop client from this link here. Follow the instructions for which machine you are using. Once installed and opened it should look something like this:

2. Pin Files to IPFS

Click on the "Files" tab in IPFS Desktop. From here you will see any files you have pinned through IPFS Desktop. To upload click "Import" in the top right.

You can either import a local file, folder, or you can import an existing IPFS CID.


When adding large folder to IPFS Desktop, make sure you add them all at once. If you add items to a folder in chunks, IPFS will unpin the original folder, then re-pin the new folder. If you do this too many times it will cause problem with local pinning, and we won't be able to pin by CID. If you have an image folder that is very large and IPFS desktop has a hard time importing it, then you may want to consider splitting the folder up and uploading each folder separately, then mapping over the multiple image folder CIDs in the metadata.

After selecting a file and it is finished uploading you should see the file appear in the file manager with the CID generated from uploading it.

If you did not enable auto uploading back in the services tab, you can pin them manually here! Just click on the options button on the right side, then select "Set Pinning."

From this modal you will want to select "Local Node."

After doing this you will see a pin status showing it is being pinned to your local node.

3. Pin Files to Pinata


Before we go any further, it is critical to understand that in order to upload with this method, the IPFS Desktop app must stay open when pinning to Pinata. The IPFS Desktop app is running a local IPFS node on your machine, sending and receiving data from other nodes. When you host a file or folder from your machine to the node, Pinata has to locate all the data from your node. If the app is closed while pinning to Pinata, the upload will not be successful. Make sure the app remains open, running, and that the machine remains on without an internet connection interruption!

From the IPFS Desktop App, copy the CID for your file

Log into your Pinata account, click on the "Upload" button, and select "CID"

Paste in the CID from your file on IPFS Desktop and give it a name you want to refer to it by in Pinata. Then click "Search and Pin."

Once you have done this and refresh the page, you will see a "Pin By CID Queue" where you can check the status of the pinning

From here you can see the status of the pinning

There are several different statuses for the pinning. Here is what each one means:


Pinata is prechecking the CID before searching, making sure it's a valid CID. e.g. if you put in random words instead of a valid CID it would fail the prechecking


Pinata is currently looking for the CID content on IPFS.

If your pin job is stuck in the searching status, that usually means we can't find the CID. You need to make sure it's properly pinned as shown in step 2, as well as any firewalls or antivirus that might be stopping the data from leaving your computer.


Pinata has found the CID and is currently pinning the content to Pinata IPFS nodes

This is a good sign! It means your content is accessible and will be completed if the IPFS Desktop app is kept running. Be aware that the speed might vary on the number of files, your internet upload speed, and the IPFS network. Pinning by CID can take anywhere from a few minutes to a whole day.


Pinata was in the middle of retrieving the files, but there was an interruption in the connection.

This happens when your computer goes to sleep, the IPFS Desktop app was closed, or your internet connection stopped. Since your computer is one of the only IPFS nodes with the content, Pinata is primarily going to pull from it.


Pinata identified the file/folder as being over the 25GB upload limit. The Pinata team can help with special cases that go over this limit, but we cannot guarantee success. Please email [email protected] for assistance.

To make sure your pin is actually retrieving, check the status page inside IPFS Desktop. From there you will see a graph of incoming and outgoing traffic of your node! When you pin by CID, Pinata's nodes will swarm your local node, causing a huge spike in outgoing traffic. If you don't see the outgoing traffic, something went wrong and you will probably need to redo the steps mentioned above!

Once the pinning is complete the job will disappear from the queue and the file will show up in your files manager!

4. Large Folders

If you are uploading a large folder, it is VERY important keep the IPFS Desktop app running. Since there will be a lot of files within the folder, it will take longer for Pinata to locate every single one and pin it to your account. If the IPFS Desktop app is closed, the node will stop broadcasting the data, and it will interrupt the connection between Pinata and your IPFS Desktop node. If this happens you can look in the Pin by CID queue on your Pinata account and it will probably say "expired." Simply restart the IPFS Desktop app, make sure the folder is pinned, then redo the pin. Make sure your computer does not fall asleep or lose internet connection to finish the process. If the folder is over 25GB you will need to email [email protected] for a custom solution since our upload limit is 25GB per file/folder.


1 - Pre-requirements:

The instructions provided in this guide must be run through what's known as "the command line".

To open this up in macOS, check out:
Once you've opened up your command line application, you can begin typing in the commands provided in the installation documentation linked above.

2 - IPFS installation:

Once you have your command line application open, the first thing you're going to need to do is visit the ipfs official distribution page located here: On this page, you'll need to scroll to your operating system and follow the instructions on how to install IPFS to your machine.

3 - Running IPFS

Once you've successfully installed IPFS, you're going to want to run it by typing ipfs daemon into your command line.

You should see something like this appear:

If you see this, congratulations, you're running IPFS on your computer!

* Please note that sometimes you might see error messages related to networking in the command line window. As long as your IPFS daemon is still running, don't worry about these messages.

4 - Adding your content to IPFS

Once you have IPFS running, the next step is going to be to add your folder to your locally running IPFS node. To do this, you'll need to open up a new tab or window for your command line application. We need to run our future commands in a new window because we need to keep the ipfs daemon running in your original command line window.

  • On MacOS Windows you can do this by typing Ctrl + Win + T on your keyboard

  • On MacOS you can do this by typing ⌘ + n

In your new terminal window, you'll need to navigate to the location where your folder is being stored in your local filesystem.
You can do this by using the cd command.

  • To navigate into a folder location on your computer, type:

cd nameOfTargetFolder

  • To navigate up a level in your computer, type:

cd ..

  • To list the contents of the current folder you're located in, you can type:


Your target location is going to be the folder that contains the folder of files you want to upload to Pinata. So if your folder is named exampleFolder and is stored in your Documents folder on you'll want to make sure you're located in the Documents folder, but not inside of the exampleFolder folder. To confirm this, if you run the ls command, you should see exampleFolder listed in the results.

Once you're at the target location, you'll want to type the following command into your command line:

ipfs add --recursive --progress ./exampleFolder/ 

From here your folder should start being added to IPFS. If you have a relatively large folder, this may take some time. You'll know once this has finished when things stop being added and the upload reaches 100%. You should receive something that looks like this:

Notice the very bottom CID that we receive? The one that has the name of exampleFolder next to it? That's what you'll want to grab.

5 - Make sure that your content is retrievable on the IFPS network.

5.1 - Before you do anything else, you'll want to check that your folder isn't too big for IPFS to transfer properly. To do this, the following command needs to be run:
​ipfs block stat CID where CID is the root CID of your folder.
​If the size of this exceeds 1000000, your content will not be discoverable!
If you run into this issue, you're likely not running go-ipfs v0.11.0 or higher. Please check this with the command ipfs version on your command line:

If you see anything less than 11, you'll need to upgrade to ipfs v0.11.0.
​Once you've enabled this, you'll need to restart your node before adding your folder again!
Once you've enabled this functionality and have re-added your content, you should receive a new CID. Run ipfs block stat CID to double check that the result here is under 1000000.

5.2 - Now that you've added your content to your node and we know it fits within the IPFS folder limits, let's double check and make sure the public ipfs network can find it. To do this, we recommend visiting:
​ (replace CID with your folder's CID)

If this returns with some text telling you about your upload, and not an error, you're good to move on to the next step!
If you receive a timeout error, this means that your local node is likely behind a firewall has connectivity issues. To resolve these, we recommend checking out this guide here:

6 - Getting Pinata to retrieve your content

Now that you've added your content to your local IPFS node, it's time for Pinata to grab it!
go to and click on the upload button and "CID":

In here, put in your CID and the name of it.

Once you've done that hit 'Search and Pin'

7 - Wait for success!

While Pinata is searching the network for your content, please be patient. Retrieval can take a long time if your folder is quite large. In addition, if your network connection is slow, this might also slow down retrieval times.
You'll know that the retrieval has finished by refreshing the pin manager every so often. Once your CID appears in the pin list, your content has been successfully pinned to Pinata!

Did this answer your question?