csv2notion

An alternative way to import *.csv files to Notion.so.

Due to current limitations of the official Notion SDK this tool is using the unofficial SDK by Jamie Alexandre notion-py.

Original idea belongs to Vigneswaran Rajkumar.

Advantages over native import

Actually merge CSV with existing database rows (not just add new ones), first column will be used as a key
Manually set column types instead of relying on autodetection
Automatically link or create new entries in relation columns based on their value
Upload files into "Files & media" column
Set icon for each row
Set cover or embed image for each row
Upload image file used for cover or icon
Options for validation of input data

Disadvantages over native import

Slower speed, since every row is imported separately
- this is mitigated by multithreaded upload

Installation

Using portable binary

Download the latest binary release for your OS.

With Homebrew (Recommended for macOS)

$ brew install vzhd1701/tap/csv2notion

With PIPX (Recommended for Linux & Windows)

$ pipx install csv2notion

With PIP

$ pip install --user csv2notion

Python 3.7 or later required.

From source

This project uses poetry for dependency management and packaging. You will have to install it first. See poetry official documentation for instructions.

$ git clone https://github.com/vzhd1701/csv2notion.git
$ cd csv2notion/
$ poetry install --no-dev
$ poetry run csv2notion

Usage

$ csv2notion --help
usage: csv2notion [-h] --token TOKEN [--url URL] [OPTION]... FILE

Import/Merge CSV file into Notion database

positional arguments:
  FILE                               CSV file to upload

general options:
  --token TOKEN                      Notion token, stored in token_v2 cookie for notion.so
  --url URL                          Notion database URL; if none is provided, will create a new database
  --max-threads NUMBER               upload threads (default: 5)
  --log FILE                         file to store program log
  --verbose                          output debug information
  --version                          show program's version number and exit
  -h, --help                         show this help message and exit

column options:
  --column-types TYPES               comma-separated list of column types to use for non-key columns;
                                     if none is provided, types will be guessed from CSV values
                                     (can also be used with --add-missing-columns flag)
  --add-missing-columns              if columns are present in CSV but not in Notion DB, add them to Notion DB
  --randomize-select-colors          randomize colors for added options in select and multi select columns

merge options:
  --merge                            merge CSV with existing Notion DB rows, first column will be used as a key
  --merge-only-column COLUMN         CSV column that should be updated on merge;
                                     when provided, other columns will be ignored
                                     (use multiple times for multiple columns)
  --merge-skip-new                   skip new rows in CSV that are not already in Notion DB during merge

relations options:
  --add-missing-relations            add missing entries into linked Notion DB

page cover options:
  --image-column COLUMN              CSV column that points to URL or image file that will be embedded for that row
  --image-column-keep                keep image CSV column as a Notion DB column
  --image-column-mode {cover,block}  upload image as [cover] or insert it as [block] (default: block)
  --image-caption-column COLUMN      CSV column that points to text caption that will be added to the image block
                                     if --image-column-mode is set to 'block'
  --image-caption-column-keep        keep image caption CSV column as a Notion DB column

page icon options:
  --icon-column COLUMN               CSV column that points to emoji, URL or image file
                                     that will be used as page icon for that row
  --icon-column-keep                 keep icon CSV column as a Notion DB column
  --default-icon ICON                Emoji, URL or image file that will be used as page icon for every row by default

validation options:
  --mandatory-column COLUMN          CSV column that cannot be empty (use multiple times for multiple columns)
  --fail-on-relation-duplicates      fail if any linked DBs in relation columns have duplicate entries;
                                     otherwise, first entry in alphabetical order
                                     will be treated as unique when looking up relations
  --fail-on-duplicates               fail if Notion DB or CSV has duplicates in key column,
                                     useful when sanitizing before merge to avoid ambiguous mapping
  --fail-on-duplicate-csv-columns    fail if CSV has duplicate columns;
                                     otherwise last column will be used
  --fail-on-conversion-error         fail if any column type conversion error occurs;
                                     otherwise errors will be replaced with empty strings
  --fail-on-inaccessible-relations   fail if any relation column points to a Notion DB that
                                     is not accessible to the current user;
                                     otherwise those columns will be ignored
  --fail-on-missing-columns          fail if columns are present in CSV but not in Notion DB;
                                     otherwise those columns will be ignored
  --fail-on-unsettable-columns       fail if DB has columns that don't support assigning value to them;
                                     otherwise those columns will be ignored
                                     (columns with type created_by, last_edited_by, rollup or formula)
  --fail-on-wrong-status-values      fail if values for 'status' columns don't have matching option in DB;
                                     otherwise those values will be replaced with default status

Input

You must pass a single *.csv file for upload. The CSV file must contain at least 2 rows. The first row will be used as a header.

Optionally you can provide a URL to an existing Notion database with the --url option; if not provided, the tool will create a new database named after the CSV file. The URL must link to a database view, not a page.

The tool also requires you to provide a token_v2 cookie for the Notion website through --token option. For information on how to get it, see this article.

Important notice. token_v2 cookie provides complete access to your Notion account. Handle it with caution.

Upload speed

Due to API limitations, the upload is performed one row at a time. To speed things up, this tool uses multiple parallel threads. Use the --max-threads option to control how fast it will go. Try not to set it too high to avoid rate limiting by the Notion server.

Duplicate CSV columns

Notion does not allow the database to have multiple columns with the same name. Therefore CSV columns will be treated as unique. Only the last column will be used if CSV has multiple columns with the same name. If you want the program to stop if it finds duplicate columns, use the --fail-on-duplicate-csv-columns flag.

Missing columns

If a CSV file has columns absent from Notion DB, they will be ignored by default. Use the --add-missing-columns flag if you want the tool to add missing columns into Notion DB. Use the --fail-on-missing-columns flag if you want the program to stop if it finds a column mismatch.

Column types

By default, the tool will try to guess column types based on their content. Alternatively, you can provide a comma-separated list of column types with the --column-types option when creating a new database or adding new columns with the --add-missing-columns flag. Since the first column in Notion DB is always text, the tool will use the list to set types for the rest of the columns.

By default, new options for select and multi_select columns are added with default (gray) color. If you want the tool to randomize colors for new options, use the --randomize-select-colors flag.

Some column types do not support assigning value to them because the database generates their content automatically. Currently these types include created_by, last_edited_by, rollup and formula. If you want the program to stop if it finds such columns in the database, use the --fail-on-unsettable-columns flag.

If the tool cannot convert the column value type properly, it will replace it with an empty string. If you want to make sure all values are correctly converted, use the --fail-on-conversion-error flag, which will stop execution in case of a conversion error.

The table below describes available cod

Csv2notion

Install / Use

README