financefs is a FUSE (Filesystem in Userspace) implementation that virtualizes historical stock and financial data from Yahoo Finance as a local directory structure.

The primary purpose of financefs is data caching. By automatically caching retrieved data as CSV files, it significantly reduces repeated requests to Yahoo Finance servers, helping to prevent potential IP blacklisting due to excessive load.

To build and install financefs from source, you must have the following installed:

• Go: Version 1.25 or later.

Execute the following command in your terminal. This command uses the jsonv2 experiment flag, which is required for proper installation of the project's dependencies.

GOEXPERIMENT=jsonv2 go install github.com/pluto-org-co/financefs/cmd/financefs@latest

After installation, execute the binary with the desired mount point path. Ensure the mount point directory exists.

# Example: Using a directory in your home folder
mkdir ~/finance_data
financefs ~/finance_data

The system will now be mounted at ~/finance_data.

Files under the mounted directory represent cached financial tickers (e.g., AAPL, ^SPX).

If a ticker is not visible, it means it is not yet cached. Simply accessing its directory will trigger the data pull and cache creation:

# Listing the mountpoint might not show 'F' (Ford) yet
ls ~/finance_data

# Accessing the directory pulls the data and creates the files
cd ~/finance_data/F

# Now the files are available
ls ~/finance_data/F
# Output: daily.csv  monthly.csv  weekly.csv

Use standard file system commands to retrieve the CSV data:

# Get all-time daily data for AAPL
head ~/finance_data/AAPL/daily.csv

To safely unmount the filesystem, use the standard umount command:

umount /path/to/mountpoint
# Example:
umount ~/finance_data

Since the data is presented as standard CSV files, it integrates seamlessly with popular data analysis tools like Pandas.

Here is a small Python program that loads the daily data for a ticker and displays the first few rows:

import pandas as pd
import os

# Define the mount point and the ticker you want to analyze
MOUNT_POINT = "~/finance_data"
TICKER = "AAPL"

# Construct the file path using the os.path.expanduser to handle the tilde (~)
data_path = os.path.expanduser(f"{MOUNT_POINT}/{TICKER}/daily.csv")

try:
    # Attempt to read the CSV file into a Pandas DataFrame
    df = pd.read_csv(data_path, index_col='time', parse_dates=True)

    print(f"✅ Successfully loaded daily data for {TICKER}:")
    print("-" * 40)
    print(df.head())

except FileNotFoundError:
    print(f"❌ Error: File not found at {data_path}. ")
    print(f"Make sure {TICKER} has been accessed on the mounted system.")
except Exception as e:
    print(f"An unexpected error occurred: {e}")

Outputs:

✅ Successfully loaded daily data for AAPL:
----------------------------------------
                           # source exchange name symbol interval currency          timezone  open  high  low  close     volume
time
1980-12-12 09:30:00-05:00  0  yahoo      NasdaqGS   AAPL    daily      USD  America/New_York    12    12   12     12  469033600
1980-12-15 09:30:00-05:00  1  yahoo      NasdaqGS   AAPL    daily      USD  America/New_York    12    12   12     12  175884800
1980-12-16 09:30:00-05:00  2  yahoo      NasdaqGS   AAPL    daily      USD  America/New_York    11    11   11     11  105728000
1980-12-17 09:30:00-05:00  3  yahoo      NasdaqGS   AAPL    daily      USD  America/New_York    11    11   11     11   86441600
1980-12-18 09:30:00-05:00  4  yahoo      NasdaqGS   AAPL    daily      USD  America/New_York    11    11   11     11   73449600

This project is released under the GNU AFFERO GENERAL PUBLIC LICENSE (AGPL-3.0). See the LICENSE file for more details.