Package: csv2notion-neo
CSV2Notion NeoAn advance method to upload & merge *.csv or *.json files with images toNotiondatabase.Core FeaturesAdvantages over native importMerge CSV or JSON with the existing database, using the first column as a key to combine existing rowsChoose column types manually instead of letting Notion detecting them automaticallyLink or create new entries in relation columns based on their values automaticallyEasily upload files into the designated "Files & Media" columnAssign a icon for each row for quick identificationSet a cover or embed an image for each row to enhance visual representationUpload image files for covers or iconsApply validation options for input data to ensure accuracyDisadvantages over native importImporting each row separately might lead to slower speedTo address this, utilise multithreaded uploadTable of contentsBackgroundInstallationPre-compiled Binary (Recommended)From SourceGuidemacOS ReleasePrerequisiteUpload SpeedDuplicate CSV ColumnsMissing ColumnsColumn TypesMerginRelation ColumnsCover Image & Embedded ImageIconsMandatory ColumnsExamplesKnown IssuesCreditsLicenseReporting BugsBackgroundOriginally, we developedcsv2notionto address the lack of advanced importing support for*.csvfiles inNotion. We took inspiration fromAirtable’sCSV import extension.CSV2Notion Neowas created as a spin-off project to address inactivity in the original repository and maintain compatibility with Notion. As Notion changes or updates its backend API periodically, we aim to fix, update and add new features to the tool in a timely manner. Any dependent tools or project that relied oncsv2notion, can use ourCSV2Notion Neotool interchangeably requiring additional augments.InstallationPre-compiled Binary (Recommended)Download the latest release of the latest binary releasehere.WithHomebrew(Recommended for macOS)$brewinstallTheAcharya/homebrew-tap/csv2notion-neo$brewuninstall--caskcsv2notion-neoWith PIP$pipinstall--usercsv2notion_neoPython 3.7 or later required.From sourceThis project usespoetryfor dependency management and packaging. You will have to install it first. Seepoetry official documentationfor instructions.$gitclonehttps://github.com/TheAcharya/csv2notion-neo.git
$cdcsv2notion_neo/
$poetryinstall--no-dev
$poetryruncsv2notion_neoGuide$ csv2notion_neo --help
usage: csv2notion_neo [-h] --token TOKEN [--url URL] [OPTION]... FILE

https://github.com/TheAcharya/csv2notion-neo

Upload & Merge CSV or JSON Data with Images to Notion Database

positional arguments:
  FILE                               CSV or JSON file to upload

general options:
  --workspace                        active Notion workspace name
  --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                      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                     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
  --rename-notion-key-column         rename the key column in the file to a different key column in Airtable
  --randomize-select-colors          randomize colors for added options in select and multi select columns

merge options:
  --merge                            merge CSV or JSON with existing Notion DB rows, first column will be used as a key
  --merge-only-column                CSV or JSON 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 or JSON 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              one or more CSV or JSON column that points to URL or image file that will be embedded for that row
  --image-column-keep                keep image CSV or JSON 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             CSV or JSON 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 or JSON column as a Notion DB column

page icon options:
  --icon-column                      CSV or JSON 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 or JSON 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                 CSV or JSON column that cannot be empty (use multiple times for multiple columns)
  --payload-key-column               JSON object that is the key in Notion DB;
                                     if JSON file is used, this cannot be empty
  --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 or JSON has duplicates in key column,
                                     useful when sanitizing before merge to avoid ambiguous mapping
  --fail-on-duplicate-csv-columns    fail if CSV or JSON 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 statusmacOS ReleasePrivacy & SecurityFor macOS, you have the option of two distinct releases: one packaged within a.ziparchive and the other in a.pkgformat. Navigate to thePrivacy & Securitysettings and set your preference toApp Store and identified developers.Utilise theCSV2Notion Neo.pkginstaller to install the command-line binary into your system. Upon completion, find the installed binarycsv2notion_neolocated within/usr/local/bin. To uninstall, you can utalise this terminal command.sudo rm /usr/local/bin/csv2notion_neoPrerequisiteYou must pass a single*.csvfile 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--urloption; 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.Obtaining Database URLObtaining Workspace NameTo see your Workspace name go toSettings & membersat the top of the left sidebar. In the window that pops up, click on theSettingstab.If your Workspace name isAcme Inc., you are required to provide--workspace "Acme Inc."as such.The tool also requires you to provide atoken_v2cookie for the Notion website through--tokenoption.Login to yourNotionaccount via a web browser.Find and copy the entiretoken_v2value includingv02%3Auser_token_or_cookies%from your Notion session.Obtaining Notion Session Token (Safari)Enable Web InspectorIf you don’t see the Develop menu in the menu bar, choose Safari, Settings, click Advanced, then select “Show features for web developers”.Press⌥ + ⌘ + ito show Web InspectorObtaining Notion Session Token (Brave, Chrome or Edge)Go to Setting, Privacy and securityImportant notice.token_v2cookie provides complete access to your Notion account. Handle it with caution.Upload SpeedDue 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-threadsoption to control how fast it will go. Try not to set it too high to avoid rate limiting by the Notion server.Duplicate CSV ColumnsNotion does not allow the database to have multiple columns with the same name. Therefore CSV columns will be treated as unique. Only thelastcolumn 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-columnsflag.Missing ColumnsIf a CSV file has columns absent from Notion DB, they will be ignored by default. Use the--add-missing-columnsflag if you want the tool to add missing columns into Notion DB. Use the--fail-on-missing-columnsflag if you want the program to stop if it finds a column mismatch.Column TypesBy 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-typesoption when creating a new database or adding new columns with the--add-missing-columnsflag. 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 forselectandmulti_selectcolumns are added with default (gray) color. If you want the tool to randomize colors for new options, use the--randomize-select-colorsflag.Some column types do not support assigning value to them because the database generates their content automatically. Currently these types includecreated_by,last_edited_by,rollupandformula. If you want the program to stop if it finds such columns in the database, use the--fail-on-unsettable-columnsflag.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-errorflag, which will stop execution in case of a conversion error.The table below describes available codes for--column-typesand what values are supported by each column type:Support TableColumn TypeNameColumn TypeCodeSupported ValuesMultiple Values(Comma Separated)BasicTexttextstring❌Numbernumbernumerical❌Selectselectstring❌Multi-selectmulti_selectstring✅Statusstatusstring❌Datedateany date format✅ (range)Personpersonusername, email✅Files & mediafilefile name, URL✅Checkboxcheckboxtrue,false❌URLurlstring❌Emailemailstring❌Phonephone_numberstring❌AdvancedFormulaformula------Relation---key, Notion URL✅Rolluprollup------Created timecreated_timeany date format❌Created bycreated_by------Last edited timelast_edited_timeany date format❌Last edited bylast_edited_by------MergingBy default, the tool will add rows to the existing Notion DB. To merge CSV rows with the Notion database, use the--mergeflag. The first column of CSV and Notion DB will be used as a key to update existing rows with new values. CSV rows that didn't have a match in Notion DB will be added as new.Since the tool treats rows as unique during merge based on the key column, it will use first found rows with a unique key. To avoid this ambiguity, you might want to validate duplicate row keys with the--fail-on-duplicatesflag. It will check both CSV and target Notion DB before the merge.If you want only select columns to be updated, use the--merge-only-columnoption.If you don't want the tool to add any new rows not already present in the Notion DB during merge, use the--merge-skip-newflag.Relation ColumnsNotion database has arelationcolumn type, which allows you to link together entries from different databases. The tool will try to match column data with keys from a linked database.By default, it will match with the first found row; it will add nothing if it cannot find the match. Use the--add-missing-relationsflag if you want the tool to create new entries in the linked DB if no match is found. Use the--fail-on-conversion-errorflag if you want the program to stop if no match is found.You can also use Notion URLs in columns of this type, and they must belong to the linked DB. The tool will not be able to add missing entries for URLs if you use the--add-missing-columnsflag.Since the tool treats rows in the linked DB as unique you can prevent ambiguous matching with the--fail-on-relation-duplicatesflag. It will check linked DB for duplicate keys and stop the executions if it finds any.If linked DB is not accessible (linked DB is deleted or your account doesn't have access to it), columns that point to it will be ignored. If you prefer the program to stop in this case, use the--fail-on-inaccessible-relationsflag.Cover Image & Embedded ImageThe tool allows you to add an image to each row with the--image-columnoption. It will use one column from CSV as a data source for the image. It can be either a URL or a file name. The file name must be either an absolute path or a path relative to the CSV file. The tool will upload the file to the Notion server.By default, the tool will embed an image inside the row page. If you want it to use the image as a page cover, then set the--image-column-modeoption tocover.Column specified with the--image-columnoption will not be treated as a regular column by default. If you want it to appear in Notion DB, use the--image-column-keepflag.To add custom caption to image block uploaded with--image-column-modeset toblock, use--image-caption-columnoption. To also keep the caption as a Notion DB column, use--image-caption-column-keepflag.IconsThe tool allows you to add an icon to each row with the--icon-columnoption. The behavior is the same as with--image-column; the only difference is that you can use URL, file name, or single emoji.To also treat--icon-columnas a regular column, use--icon-column-keepflag, similar to--image-column-keep.If you want to set the same icon for each row, use the--default-iconoption. If both--icon-columnand--default-iconare present, the default icon is used if the row doesn't have anything in the icon column.Mandatory ColumnsIf you want to ensure that specific columns always have value and are not allowed to be empty, then use the--mandatory-columnoption. The program execution will stop if validation fails.ExamplesImporting CSV into New Databasecsv2notion_neo--workspaceYOUR_WORKSPACE_NAME_HERE--tokenYOUR_TOKEN_HEREtest.csvUsing Custom Column Typescsv2notion_neo--workspaceYOUR_WORKSPACE_NAME_HERE--tokenYOUR_TOKEN_HERE--column-types"number,multi_select"test.csvImporting CSV into Existing Databasecsv2notion_neo--workspaceYOUR_WORKSPACE_NAME_HERE--tokenYOUR_TOKEN_HERE--urlNOTION_URLtest.csvMerging CSV with Existing Databasecsv2notion_neo--workspaceYOUR_WORKSPACE_NAME_HERE--tokenYOUR_TOKEN_HERE--urlNOTION_URL--mergetest.csvMerging CSV with Select Columns in Existing Databasecsv2notion_neo--workspaceYOUR_WORKSPACE_NAME_HERE--tokenYOUR_TOKEN_HERE--urlNOTIONURL--merge--merge-only-column"Column 2"--merge-onLy-column"Column 3"test.csvImporting Rows with Imagescsv2notion_neo--workspaceYOUR_WORKSPACE_NAME_HERE--tokenYOUR_TOKEN_HERE--image-column"Image Column"test.csvImporting Rows with Images (Multiple Image Column)csv2notion_neo--workspaceYOUR_WORKSPACE_NAME_HERE--tokenYOUR_TOKEN_HERE--image-column"Colour Image""Black & White Image""Map"--image-column-keep--mandatory-column"Cat ID"test.csvExample CSVCat ID,Animal Name,Location,Colour Image,Black & White Image,Map
1,Lion,Namibia,Colour/lion.jpg,Black & White/lion.jpg,Map/Namibia.jpg
2,Tiger,India,Colour/tiger.jpg,Black & White/tiger.jpg,Map/India.jpg
3,Panther,India,Colour/panther.jpg,Black & White/panther.jpg,Map/India.jpg
4,Snow Leopard,Nepal,Colour/snow_leopard.jpg,Black & White/snow_leopard.jpg,Map/Nepal.jpg
5,Cheetah,South Africa,Colour/cheetah.jpg,Black & White/cheetah.jpg,Map/South Africa.jpg
6,Puma,South America,Colour/puma.jpg,Black & White/puma.jpg,Map/South America.jpg
7,Jaguar,Brazil,Colour/jaguar.jpg,Black & White/jaguar.jpg,Map/Brazil.jpgExample Folder Structure├─ Data/
│  ├─ test.csv
│  ├─ Black & White/
│  │  ├─ cheetah.jpg
│  │  ├─ jaguar.jpg
│  │  ├─ lion.jpg
│  │  ├─ panther.jpg
│  │  ├─ puma.jpg
│  │  ├─ snow_leopard.jpg
│  │  ├─ tiger.jpg
│  ├─ Colour/
│  │  ├─ cheetah.jpg
│  │  ├─ jaguar.jpg
│  │  ├─ lion.jpg
│  │  ├─ panther.jpg
│  │  ├─ puma.jpg
│  │  ├─ snow_leopard.jpg
│  │  ├─ tiger.jpg
│  ├─ Map/
│  │  ├─ Brazil.jpg
│  │  ├─ India.jpg
│  │  ├─ Namibia.jpg
│  │  ├─ Nepal.jpg
│  │  ├─ South Africa.jpg
│  │  ├─ South America.jpg
│  │  ├─ tiger.jpgImporting Rows with Emoji Iconscsv2notion_neo--workspaceYOUR_WORKSPACE_NAME_HERE--tokenYOUR_TOKEN_HERE--icon-column"Icon Column"test.csvUpdating Emoji Icon Only for All Rowscsv2notion_neo--workspaceYOUR_WORKSPACE_NAME_HERE--tokenYOUR_TOKEN_HERE--urlNOTION_URL--default-icon👍--merge--merge-only-column"Key"test.csvImporting JSON into Existing Databasecsv2notion_neo--workspaceYOUR_WORKSPACE_NAME_HERE--tokenYOUR_TOKEN_HERE--urlNOTION_URL--mandatory-column"Cat ID"--payload-key-column"Cat ID"--mergeJSON-Demo.jsonImporting JSON into Existing Database with a Different Key Columncsv2notion_neo--workspaceYOUR_WORKSPACE_NAME_HERE--tokenYOUR_TOKEN_HERE--urlNOTION_URL--mandatory-column"Cat ID"--payload-key-column"Cat ID"--rename-notion-key-column"Cat ID""Anything ID"--mergeJSON-Demo.jsonKnown IssuesUsers would not be able to duplicate entries/records there where uploaded usingCSV2Notion Neoin Notion.Workaround:Simplyduplicatethe database directly in Notion. You would be able to duplicate your entries/records in the duplicated database.Utilised ByCommandPostCommandPost's Notion ToolboxCreditsOriginal Idea and Workflow Architecture byVigneswaran RajkumarMaintained byArjun Prakash(1.0.0 ...)Original Work byVladilen ZhdanovIcon Design byBor Jen GohLicenseLicensed under the MIT license. SeeLICENSEfor details.Reporting BugsFor bug reports, feature requests and other suggestions you can createa new issueto discuss.