q
q is a command-line tool that lets you run SQL queries directly on CSV, TSV, and other delimited text files, as well as SQLite databases, without converting or importing data first. It caches query results to dramatically speed up repeated queries on large files.
Key facts
Objective fields from the source. Values we can't verify are shown as “Unknown” rather than guessed.
| Field | Value |
|---|---|
| Repository | harelba/q |
| Owner | harelba |
| Primary language | Python |
| License | GPL-3.0 — OSI-approved |
| Stars | 10.4k |
| Forks | 423 |
| Open issues | 130 |
| Latest release | v3.1.6 (2021-11-26) |
| Last updated | 2026-02-06 |
| Source | https://github.com/harelba/q |
What q is
Written in Python, q parses delimited text files as virtual tables and executes SQL statements (SELECT, WHERE, GROUP BY, JOIN, etc.) against them via an embedded SQLite engine. Optional disk-based caching can accelerate repeated queries by 25–150× depending on data volume and column count.
Get the q source
Clone the repository and explore it locally.
git clone https://github.com/harelba/q.gitcd q# follow the project's README for install & configurationNeed it deployed, integrated, or customized instead? DEV.co ships production installs.
Best use cases
Implementation considerations
- Installation via package manager or direct download from project site; no complex dependencies noted. Verify Python version compatibility for your environment.
- Caching is disabled by default due to disk usage; explicitly enable with `-C readwrite` or `-C read` flags or via `.qrc` config file to realize performance gains.
- Column auto-detection works for most common delimiters; may require manual column specification for edge cases (unusual encodings, nested delimiters).
- For very large files (multi-GB), on-disk caching is essential; understand cache storage location and cleanup requirements.
- Encoding support is stated; test with non-UTF-8 data in your pipeline to confirm compatibility.
When to avoid it — and what to weigh
- Real-time or High-frequency Querying — q parses and caches on disk; not designed for millisecond-latency queries or streaming data. Use a real database for production OLTP workloads.
- Complex Data Validation or Transformation Pipelines — q is a query tool, not an ETL framework. For multi-step transformations, data quality checks, and schema enforcement, consider dbt, Apache Beam, or dedicated data pipeline tools.
- Enterprise Multi-user Access Control — No user authentication, row-level security, or audit logging. Not suitable for shared production databases or compliance-heavy environments.
- Windows as Primary Platform — Tool is optimized for Linux/Unix environments. Windows support exists but is not the primary target; verify compatibility for your use case.
License & commercial use
Licensed under GPL-3.0 (GNU General Public License v3.0). This is a strong copyleft license requiring that any derivative work or distribution must also be released under GPL-3.0.
GPL-3.0 is a copyleft license. You may use q commercially for internal analysis and querying. However, if you integrate q into a product you distribute, ship, or license to others, the entire product must be released under GPL-3.0. Requires legal review before incorporating into proprietary tools or products.
DEV.co evaluation signals
Editorial assessment — not user reviews. Directional, with an explicit confidence level.
| Signal | Assessment |
|---|---|
| Maintenance | Active |
| Documentation | Strong |
| License clarity | Clear |
| Deployment complexity | Low |
| DEV.co fit | Possible |
| Assessment confidence | High |
q executes SQL on local files with no authentication layer. Ensure only trusted users have access to the tool and input files. No mention of input sanitization, SQL injection prevention, or threat modeling. If processing untrusted CSV data, review for malformed input handling. No encryption for cached files; cache is stored on disk unencrypted. Not suitable for sensitive data without additional file-system security controls.
Alternatives to consider
DuckDB
Modern columnar SQL engine with similar file-querying capabilities, faster performance on large datasets, and active development. Available as library or CLI. Apache 2.0 license is more permissive.
ClickHouse Local
Designed for large-scale analytics on local files; offers superior performance for multi-billion-row queries. Steeper learning curve; not as lightweight as q.
SQLite CLI
Native SQLite command-line tool; requires manual import/conversion step. No caching or CSV auto-parsing, but offers full SQL and zero external dependencies.
Build on q with DEV.co software developers
If you need to query large text files or multi-file SQLite databases from the CLI, test q in a non-critical environment first. Verify GPL-3.0 license terms with your legal team if you plan to distribute or integrate it into products.
Talk to DEV.coRelated open-source tools
Surfaced by semantic similarity across the DEV.co open-source index.
Related on DEV.co
Explore the category and the services that help you build with it.
q FAQ
Does q require a database server?
What file formats does q support?
Is caching enabled by default?
Can I use q in production?
Software developers & web developers for hire
Need help beyond evaluating q? DEV.co is a software development agency offering software development services and web development for teams of every size. Our software developers and web developers build custom software, web applications, APIs, and open-source databases integrations — and maintain them long-term.
Evaluate q for Your Team
If you need to query large text files or multi-file SQLite databases from the CLI, test q in a non-critical environment first. Verify GPL-3.0 license terms with your legal team if you plan to distribute or integrate it into products.