How to Upload Files to IPFS: Complete Guide for Devs

Everything you need to know about handling IPFS files, metadata and directories.
Written by
Mantas Ciuksys
August 27, 2023
min. read

IPFS, the InterPlanetary File System, offers a new horizon for data storage—removing central points of failure, ensuring data permanence, and providing an uncensorable web. As developers, diving into IPFS may seem like navigating a new galaxy, but it’s not as complex as it may first seem - and if you have a guide to follow it makes it a whole lot easier. This guide, tailored specifically for devs, breaks down the essentials of uploading files to IPFS. From single files to expansive directories, and general methods to streamlined solutions like the Tatum API.

What Is IPFS? 

IPFS, short for the Interplanetary File System, is a peer-to-peer distributed file system designed to make the web faster, more resilient, and more open. It decentralizes data storage by addressing content based on its unique cryptographic hash rather than a physical location. 

This ensures data integrity, reduces redundancy, and eliminates the pitfalls of centralized data storage. In the blockchain context, where decentralization and data consistency are crucial, IPFS stands as an essential tool, allowing developers to offload bulky data while maintaining a reference on the blockchain.

In short, IPFS is a peer-to-peer distributed file system that seeks to connect all computing devices with the same system of files. Let's break that down further:

  • Content Addressable: IPFS addresses content by what it is, not where it's at. It uses a cryptographic hash of the file's content, ensuring that content can't be tampered with without changing the address.
  • Distributed: Instead of relying on central servers, IPFS retrieves files from multiple hosts. Picture a sea of nodes; when one goes down, the system remains unbroken, unlike the centralized model where one server outage could mean content is inaccessible.
  • Truly Decentralized: The more popular a piece of content becomes on IPFS, the faster its retrieval becomes, due to the higher number of nodes that host it. Think BitTorrent swarms, but designed for everything digital.
  • Permanent Web: Tired of seeing “404 Not Found?” With IPFS, content is permanent because of its content-addressable nature. Once it's on IPFS, it's there as long as IPFS exists. 
  • Reduced Redundancy: IPFS has deduplication built-in. If two files have parts that are identical, IPFS ensures that the network only stores that part once. This way, data storage is optimized, and redundancy is minimized.

In a blockchain context, where immutability, decentralization, and integrity are key, IPFS becomes an invaluable tool. Instead of bloating the chain with large amounts of data, developers can store the data on IPFS and then only reference the content hash on the blockchain. Elegant, efficient, and clever.

In essence, IPFS is the foundation for a new web, a web where content is permanent, decentralized, and user-centric.

How to Upload Files to IPFS

Uploading files to IPFS will give your data a permanent digital stamp of authenticity and accessibility. There are multiple ways to go about it, from command-line tools to dedicated platforms. We’ll share a general way to do it and then a quicker method using the Tatum API.

General Method via Command Line:

1. Installation:

First, install IPFS. Depending on your operating system, the steps may vary. Typically, you can use a package manager or download pre-built packages. We’ll use Homebrew for Mac, Snap for Linux and Chocolatey for Windows

2. Initialization:

Initialize your IPFS repository. This creates the required configuration files and generates a new keypair.

3. Starting the Daemon:

Before adding files, you need to start the IPFS daemon.

4. Add Files:

Simply use the add command followed by the file path and name.

Or if you’re using relative file path:

You'll get a unique hash (CID) for your file. This hash acts as the address for your content in the IPFS ecosystem. It will looks something like this:


Using the Tatum API:

Using the Tatum API simplifies blockchain and IPFS operations. Here's how you can upload files to IPFS using the Tatum API:

2. Uploading Your File:

You can upload files to IPFS instantly using the Tatum API using the following call:

After you've uploaded your file, be it through the command line or the Tatum API, you can access it through any IPFS gateway using the given hash.

How to Upload Metadata to IPFS

Uploading metadata to IPFS is a common practice, especially in blockchain applications where compact, verifiable records are essential. Metadata, being structured data about data, might come in the form of JSON, XML, or other standardized formats. 

It's crucial to understand that storing your metadata involves a series of ordered steps. Initially, you upload the data to IPFS. Following that, you construct a JSON structure linking to the uploaded file. This JSON is then uploaded to IPFS. 

General Method via Command Line:

1. Preparing Metadata:

Start by crafting your metadata, typically in a JSON or XML file. Let's say you have a metadata.json file.

2. Add Metadata to IPFS:

The process is similar to adding standard files. After initializing IPFS and starting the daemon, use the add command. See the previous section on “How to Upload Files to IPFS” to see how to handle IPFS uploads. 

Upload Metadata Using the Tatum API:

If you're leaning on the Tatum API for streamlining blockchain and IPFS operations, uploading metadata becomes even more straightforward:

1) Prepare Metadata for the API:

Convert your metadata, typically structured as JSON, into a buffer or readable stream, suitable for uploading to IPFS.

2) Upload Metadata using Tatum API:

As with files, use the API's dedicated IPFS function to upload your metadata.

Once your metadata is uploaded, you can effortlessly use the returned hash to integrate with blockchain contracts, ensuring that your digital assets or projects maintain a persistent, decentralized record. As always, for the most up to date methods and detailed nuances, consult the Tatum API documentation.

How to Upload NFTs to IPFS

Uploading NFTs to IPFS essentially follows the same logic as uploading files. You can follow the steps above to successfully upload NFT data and metadata to the IPFS directory. 

The below video tutorial details how to do this using the Tatum API:

The IPFS Upload Directory

In the ecosystem of IPFS, not only can individual files be uploaded, but entire directories can be stored too. This capability is particularly beneficial when aiming to maintain the directory structure of projects, batches of files, or complex applications. Below, we'll outline the steps to uploading directories to IPFS using a general method, followed by an example of how the Tatum SDK can make that simpler. 

General Method via Command Line:

1. Upload the Directory:

To upload an entire directory and its contents (including sub-directories) to IPFS, simply use the add command with the -r (or --recursive) flag followed by the directory name.

This command will recursively upload all files and sub-directories under the chosen directory, retaining their structure. Each file and sub-directory will be assigned its own hash, but the primary hash representing the entire directory will be the one for the top-level directory.

2. Accessing Content:

Individual files or subdirectories within the uploaded directory can be accessed using the directory's hash combined with the relative path.

Uploading Directories to IPFS Using the API:

Using Tatum SDK, the process is significantly streamlined, but most importantly it integrates seamlessly with other API functionalities that help you build your app quicker. 

1. Upload Directory with the Tatum SDK:

Begin by converting your directory into an appropriate format (like a tarball or zip). Next, read this into a buffer or readable stream, ready for upload in the same manner as files and metadata.

2. Accessing Content

As with the general method, the returned hash allows you to access specific files or sub-directories on IPFS, be it through gateways or direct node interactions.

Always crosscheck with Tatum’s full documentation for latest updates and streamlined functionality on handling IPFS uploads. 


This guide has aimed to illuminate the path for devs navigating IPFS, from individual files to structured directories. As with all technologies, it's essential to keep pace with updates and best practices. So, whether you're integrating IPFS into your next project or merely exploring the decentralized web, remember: it's not just about storing data; it's about pioneering a more open, resilient, and user-centric digital future. Happy coding!