# ragflow-upload: a batch uploader that walks a directory into a RAGFlow knowledge base > ragflow-upload is a Python tool that recursively walks a directory, uploads each document to a RAGFlow knowledge base and triggers parsing, with per-file progress tracking so an interrupted run resumes rather than restarting. It suits a RAGFlow user who has hundreds of documents to ingest by hand, and the current client requires RAGFlow v0.26.2 or later. **Samge0/ragflow-upload** — 自动批量上传并解析文档至 RagFlow 知识库，省去手动操作，提升效率。 - Repository: https://github.com/Samge0/ragflow-upload - Stars: 538 · Forks: 66 - Language: Python - License: MIT - Published: 2026-10-22 · Updated: 2026-10-22 · Language: en - Canonical page: https://hysenlabs.com/projects/samge0-ragflow-upload ## The problem it solves, stated in the author's terms The repository is a tool for automatically batch uploading and parsing documents into a RAGFlow knowledge base, so as to remove the manual work and improve efficiency. The reason it exists is given plainly. RagFlow's default knowledge base upload interface has some limitations: each time you can only upload a limited number of files, and when you need to upload a large number of files, the operation can become tedious. The tool walks a specified directory and its subdirectories, uploads each document to the RagFlow knowledge base one by one, and parses it. When you have a lot of files to upload, it reduces the waiting time of manual batch uploading and parsing. The author gives a personal example of the scale that prompted it: needing to import all the notes from a Mac into a knowledge base. The feature list has six items, and each is a specific piece of work rather than a description. Batch upload supports uploading documents to the RAGFlow knowledge base in bulk. Automatic parsing performs chunking and parsing after the upload. Progress monitoring watches document parsing progress in real time. Metadata management supports setting custom metadata for documents. Processing progress recording automatically records the processing status of each file, so an interrupted run skips files already completed when it is started again. And the pure API and SDK mode means no database dependency, built entirely on the RAGFlow API and SDK. That last point is the design decision that separates this from the category of upload tooling that keeps its own state store. The progress record here is a file on disk, not a service. The requirements file is three lines long: requests, pytz and ragflow-sdk, with the SDK pinned at 0.26.2, which matches the RAGFlow version the client targets. The primary language is Python, the licence is MIT, the default branch is main, and the last push was on 2026-09-02. The recent releases are v1.0.7+ragflow0.26.2 from 2026-06-30, v1.0.6-alpha from 2025-07-22 and v1.0.5 from 2025-07-06. ## Two clients, and a version gap you have to read before installing There is a standalone client in the Releases section, and the readme explains how to configure it through a linked issue, and how to build your own executable for Windows, macOS or Linux from the instructions in scripts/README.md. But the version story is the part to read carefully, because the current release is eleven months after the previous one and the gap is not cosmetic. The readme states that RAGFlow v0.26.2 and later users should download the latest v1.0.7+ragflow0.26.2, because the tool has been refactored on the new API and SDK. Users on older RAGFlow versions, around v0.19, cannot use the new client because the RAGFlow API changed substantially, and should continue to use v1.0.6-alpha, last updated on 2025-07-22. So the client version is tied to the RAGFlow version, not to the tool's own feature set. That is a direct consequence of the API-only design, and it is the practical cost of depending on someone else's API without a compatibility layer. The packaged client and the source run differ in how you configure them. The note says the configuration method described applies to running from source. If you use the packaged client from Releases, you fill in the configuration in the graphical interface on startup and do not need to edit a configuration file by hand. The system requirements for the source path are Python 3.13 or later and RAGFlow v0.26.2 or later. The project homepage is at samge0.github.io/ragflow-upload, and the readme points at the RAGFlow official documentation at ragflow.io/docs for the server side. ## Installing from source and filling in the configuration The source install is three steps: clone, create an environment, install dependencies. ```bash git clone https://github.com/Samge0/ragflow-upload.git cd ragflow-upload ``` The environment can be conda or uv, and the readme shows both. ```bash # 使用 miniconda conda create -n ragflow-upload python=3.13 -y conda activate ragflow-upload # 或使用 uv uv venv --python 3.13 ``` Then the dependencies. ```bash pip install -r requirements.txt ``` For the source run, you copy ragflows/configs.demo.py to ragflows/configs.py and edit the result. The configuration keys are grouped into four sections, and the API section comes first. ```python API_URL = 'http://localhost:80/api/v1' # API服务器地址 API_KEY = 'ragflow-xxxxxx' # API密钥 DATASET_ID = 'dataset-12345' # 知识库ID DATASET_NAME = 'my_dataset' # 知识库名称 CHUNK_METHOD = 'naive' # 分块方法 DOC_DIR = '/path/to/documents' # 文档目录 DOC_SUFFIX = 'md,txt,pdf,docx' # 支持的文件后缀 DOC_MIN_LINES = 6 # 最小文件行数 ``` The four API keys are the address of the server, the key, and the identifier and name of the dataset you are uploading into. The API_URL has the /api/v1 path baked into the example, so it points at the API root rather than the web interface. The second group controls what is uploaded. CHUNK_METHOD selects the RAGFlow chunking strategy, DOC_DIR is the directory to walk, DOC_SUFFIX is the comma-separated list of extensions, and DOC_MIN_LINES is a minimum file line count, which exists so that stray small files in the tree do not become documents. Getting the API key has a documented path through the web interface: click the user avatar at the top right of the Ragflow home page, then the API item at the bottom left, then API KEY, then create a new key, and copy the key that starts with ragflow-. The readme also names the URL pattern, {Ragflow首页URL}/user-setting/api, and says to put the key in the API_KEY setting. One thing the tool will not do for you: the dataset has to exist already. The troubleshooting section says to create the knowledge base manually in the RAGFlow web interface first. ## Running it, and the chunking choices that change your results The run command is executed from the project root, either with Python or with uv. ```bash # Python 方式 python -m ragflows.main # uv 方式 uv run python -m ragflows.main ``` The -m form is not incidental. The troubleshooting section explains that a ModuleNotFoundError for ragflows usually does not happen inside an IDE such as vscode or pycharm but can happen when running directly in a terminal, and the recommended fix is to use the -m form from the project root, which needs no PYTHONPATH setting. The alternative is to set PYTHONPATH to the current directory yourself, with export PYTHONPATH=. on Linux and macOS, set PYTHONPATH=. in Windows CMD, and the PowerShell equivalent setting PYTHONPATH to a dot, then run python ragflows/main.py. Before running, you put documents into the configured DOC_DIR. The supported formats are .md, .txt, .pdf and .docx, matching the DOC_SUFFIX default, and you can optionally add metadata files. The chunking method is the setting that most affects what your retrieval will look like afterwards, and RAGFlow supports eight of them. The eight options are naive for simple chunking of general documents, general for mixed content, paper for academic papers, book for long books, laws for legal texts, presentation for slides, manual for technical manuals and qa for question and answer pairs. The default is naive, which is simple chunking for general documents. The alternatives exist because a technical manual and a legal document have structures that a generic chunker will split badly. Since the choice is per run rather than per dataset, a sensible workflow is to ingest a sample with naive and then again with the method that matches your document type, and compare. Metadata is handled through sidecar files. To add metadata to a document, create a file with the same name ending in .meta.json, so a directory holds report.pdf, report.pdf.meta.json, manual.docx and manual.docx.meta.json. The format is a plain JSON object with fields such as author, category, tags and version. ## Resuming after an interruption, and the chunking of parse failures The progress recording is the feature that turns a long upload job into something you can interrupt. The tool automatically records the processing status of each file, with states for pending, uploaded, parsing, complete and failed. When it is run again after an interruption, it automatically skips files that are already complete and only continues with the unfinished or failed ones. That is the difference between a tool you can leave running and a tool you have to babysit. Uploading and parsing a few hundred documents takes long enough that something will go wrong, and without a resume mechanism the only recovery is to delete everything and start over. The state lives in cache files under the user directory, and the readme gives the way to clear them. ```bash # Windows del ~/.ragflow_upload/state_*.json # Linux/Mac rm ~/.ragflow_upload/state_*.json ``` Deleting those files is how you start again from scratch, which you would want after changing the chunk method, since the recorded state reflects an upload that happened under the previous settings. The parsing configuration adds a few knobs worth understanding. ONLY_UPLOAD set to True uploads without parsing, which is the mode to use when you want to control when the parsing work starts, or to check the uploads first. PROGRESS_CHECK_INTERVAL sets how often the parse progress is polled, ENABLE_PROGRESS_LOG turns on the progress log, and FIRST_PARSE_WAIT_TIME sets a wait before the first parse check. The readme also lists what the tool does not do for you. The dataset must exist. And the API key must be valid and unexpired, since an authentication failure or an API connection error usually means the API_KEY setting is wrong or the API_URL is pointing somewhere else. The repository layout matches the design: a ragflows/ package holding the main module and the configs, a utils/ directory, a scripts/ directory holding the build instructions and the icon, a docs/ directory, and requirements.txt at the root. ## Conclusion ragflow-upload fits a RAGFlow user who has more documents than the web upload interface handles and wants parsing triggered automatically with a resumable run. It does not fit a user on an older RAGFlow release, since the current client is built against the v0.26.2 API and the earlier v1.0.6-alpha client is the one to use there, and it does not create the knowledge base for you, which has to exist first in the web interface. Before running, copy ragflows/configs.demo.py to ragflows/configs.py and check the chunk method against the table of options. ## FAQ ### What does ragflow-upload do and what does it need? It walks a directory and its subdirectories, uploads each document to a RAGFlow knowledge base and triggers parsing, with progress tracking so an interrupted run resumes. It requires Python 3.13 or later and RAGFlow v0.26.2 or later, and it works purely through the RAGFlow API and SDK with no database dependency. ### Which ragflow-upload client should I download for my RAGFlow version? For RAGFlow v0.26.2 and later, download v1.0.7+ragflow0.26.2, which is refactored on the new API and SDK. For older RAGFlow versions around v0.19, the new client is not compatible and you should use v1.0.6-alpha, last updated on 2025-07-22. ### How do I configure ragflow-upload when running from source? Copy ragflows/configs.demo.py to ragflows/configs.py and edit it, setting API_URL, API_KEY, DATASET_ID and DATASET_NAME, then the document settings CHUNK_METHOD, DOC_DIR, DOC_SUFFIX and DOC_MIN_LINES. If you use the packaged client from Releases you fill in the same settings in its graphical interface instead. ### How do I make ragflow-upload restart an interrupted upload? Nothing is needed. The tool records the status of each file, pending, uploaded, parsing, complete or failed, and on the next run it skips completed files and continues with the unfinished or failed ones. To start over from scratch, delete the state_*.json files in ~/.ragflow_upload. ## Sources - [Issues](https://github.com/Samge0/ragflow-upload/issues) - [License: MIT](https://github.com/Samge0/ragflow-upload/blob/main/LICENSE) - [README](https://github.com/Samge0/ragflow-upload/blob/main/README.md) - [Releases](https://github.com/Samge0/ragflow-upload/releases) - [Samge0/ragflow-upload on GitHub](https://github.com/Samge0/ragflow-upload) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/samge0-ragflow-upload