# A simple (and fast) requirements.txt file generator
[](https://pypi.org/project/preqs)
[](https://pypi.org/project/preqs)
[](https://pypi.org/project/preqs)
[](https://pypi.org/project/preqs)
[](https://pypi.org/project/preqs)
[](https://pypi.org/project/preqs)
[](https://pypi.org/project/preqs)
[](https://opensource.org/license/gpl-3-0)
[](https://pypi.org/project/preqs)
The `preqs` project is a cross-platform, simple, fast and easy-to-use requirements file generator. Your project's imported dependencies are collected into a `requirements.txt` file. No more, no less.
## Installation
Installing `preqs` is quick and easy. As a design feature, the library does not have any external (non-built-in) dependencies.
```
pip install preqs
```
## Usage
The help (or usage) menu can be displayed, as below, using the following command from the terminal:
```
preqs --help
```
Which displays:
```
usage: preqs [PATH] [options]
A simple (and fast) requirements.txt file generator.
positional arguments:
PATH Path to the project's root directory.
Alternatively, the path where the search for modules should start.
Defaults to the current directory.
options:
-d, --debug Print verbose debugging output while processing.
-i IGNORE_DIRS [IGNORE_DIRS ...], --ignore_dirs IGNORE_DIRS [IGNORE_DIRS ...]
One or more director(y|ies) to be ignored when collecting module files.
-p, --print Print the detected requirements, rather than creating a file.
-r, --replace Replace the current requirements.txt file.
-h, --help Display this help and usage, then exit.
-v, --version Display the version and exit.
preqs <installed version>
```
## Usage Example
In its simplest form, `preqs` can be run by just calling the program from within your project's root directory, without any arguments. The path from which the Python module discovery begins defaults to the *current directory*. If your project is in another directory, pass that directory's path into the `PATH` argument. The requirements file is saved into the path provided.
**Notes:**
- The following examples assume you are already in your project's root directory, therefore `PATH` is not provided.
- Any of the following flags may be combined to form your own requirements cocktail.
### Case 1: Simplest form
Simply generate a requirements file for your project, as:
1. Run `preqs` as:
```bash
preqs
```
2. Check the current directory for a `requirements.txt` file containing the project's external dependencies.
### Case 2: Ignoring directories
If you wish to exclude a directory (or directories) from the requirements file, the `--ignore_dirs` flag may be used as:
1. Run `preqs` as:
```bash
preqs --ignore_dirs docs build
```
2. Check the current directory for a `requirements.txt` file containing the project's external dependencies.
### Case 3: Display only (do not generate a file)
In some cases, for example with an existing requirements file you do not want to overwrite, you may wish to *display* the requirements to the terminal. This can be accomplished using the `--print` flag, as:
1. Run `preqs` as:
```bash
preqs --print
```
2. Watch the terminal for an output displaying the project's requirements.
### Case 4: Overwrite an existing requirements file
By default, if a `requirements.txt` file exists, you will be alerted. The existing file will *not* be overwritten. That is, unless you tell `preqs` it's OK.
1. Run `preqs` as:
```bash
preqs --replace
```
2. Check the current directory for a *new* `requirements.txt` file containing the project's external dependencies.
## Additional information
### How is the version number obtained?
The version number you see in the requirements file output is obtained using the built-in `importlib` library. Therefore, the package *must be installed* in the environment being used to run `preqs`.
- By design, we do *not* use PyPI to obtain version numbers as this practice usually involves assuming the latest version - whereas this may not be the case for your project.
- Any packages which are known to be imported by the project, and yet do not appear in the requirements file, *are likely not installed* in the environment. Run `preqs` with the `--print` flag to observe any packages which are imported for which the version number could not be obtained. These 'unknown version' packages are (currently) ignored when the requirements file is written.
### I don't see a specific package in the requirements file.
Refer to the *How is the version number obtained?* question.
### Why should I not just use `pip freeze`?
Many online 'tutorials' for generating a requirements file say to use `pip freeze` and redirect the output to a file called `requirements.txt`. However, this is not good practice for the following reasons:
- *All* of the packages installed in your development environment will be listed in the requirements file. This may include some (or many) packages which your project does not require, thus bloating the end-user's installation and thereby cluttering their environment. Or, the packages you have in your environment, although not used by the project, may be out-of-date; causing the end-user to be forced to install out-of-date packages.
- A true requirements file should contain *only* those packages which are imported and required by the project.
- Only the packages that were installed with `pip install` will be included in the requirements file.
Raw data
{
"_id": null,
"home_page": null,
"name": "preqs",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "build, development, requirements, setup, utilities",
"author": null,
"author_email": "The Developers <development@s3dev.uk>",
"download_url": "https://files.pythonhosted.org/packages/7d/9f/dedb2a9ee1405233ed0110e0192f8c1688f5959cc08ad9ab6b36204e143e/preqs-0.1.0.tar.gz",
"platform": null,
"description": "# A simple (and fast) requirements.txt file generator\n\n[](https://pypi.org/project/preqs)\n[](https://pypi.org/project/preqs)\n[](https://pypi.org/project/preqs)\n[](https://pypi.org/project/preqs)\n[](https://pypi.org/project/preqs)\n[](https://pypi.org/project/preqs)\n[](https://pypi.org/project/preqs)\n[](https://opensource.org/license/gpl-3-0)\n[](https://pypi.org/project/preqs)\n\nThe `preqs` project is a cross-platform, simple, fast and easy-to-use requirements file generator. Your project's imported dependencies are collected into a `requirements.txt` file. No more, no less.\n\n\n## Installation\nInstalling `preqs` is quick and easy. As a design feature, the library does not have any external (non-built-in) dependencies.\n```\npip install preqs\n```\n\n## Usage\nThe help (or usage) menu can be displayed, as below, using the following command from the terminal:\n```\npreqs --help\n```\nWhich displays:\n```\nusage: preqs [PATH] [options]\n\nA simple (and fast) requirements.txt file generator.\n\npositional arguments:\n PATH Path to the project's root directory.\n Alternatively, the path where the search for modules should start.\n Defaults to the current directory.\n\noptions:\n -d, --debug Print verbose debugging output while processing.\n -i IGNORE_DIRS [IGNORE_DIRS ...], --ignore_dirs IGNORE_DIRS [IGNORE_DIRS ...]\n One or more director(y|ies) to be ignored when collecting module files.\n -p, --print Print the detected requirements, rather than creating a file.\n -r, --replace Replace the current requirements.txt file.\n \n -h, --help Display this help and usage, then exit.\n -v, --version Display the version and exit.\n\npreqs <installed version>\n```\n\n\n## Usage Example\nIn its simplest form, `preqs` can be run by just calling the program from within your project's root directory, without any arguments. The path from which the Python module discovery begins defaults to the *current directory*. If your project is in another directory, pass that directory's path into the `PATH` argument. The requirements file is saved into the path provided. \n\n**Notes:** \n- The following examples assume you are already in your project's root directory, therefore `PATH` is not provided.\n- Any of the following flags may be combined to form your own requirements cocktail.\n\n### Case 1: Simplest form\nSimply generate a requirements file for your project, as:\n\n1. Run `preqs` as:\n```bash\npreqs\n``` \n2. Check the current directory for a `requirements.txt` file containing the project's external dependencies.\n\n### Case 2: Ignoring directories\nIf you wish to exclude a directory (or directories) from the requirements file, the `--ignore_dirs` flag may be used as:\n\n1. Run `preqs` as:\n```bash\npreqs --ignore_dirs docs build\n```\n2. Check the current directory for a `requirements.txt` file containing the project's external dependencies.\n\n### Case 3: Display only (do not generate a file)\nIn some cases, for example with an existing requirements file you do not want to overwrite, you may wish to *display* the requirements to the terminal. This can be accomplished using the `--print` flag, as:\n\n1. Run `preqs` as:\n```bash\npreqs --print\n```\n2. Watch the terminal for an output displaying the project's requirements.\n\n### Case 4: Overwrite an existing requirements file\nBy default, if a `requirements.txt` file exists, you will be alerted. The existing file will *not* be overwritten. That is, unless you tell `preqs` it's OK.\n\n1. Run `preqs` as:\n```bash\npreqs --replace\n```\n2. Check the current directory for a *new* `requirements.txt` file containing the project's external dependencies.\n\n\n## Additional information\n\n### How is the version number obtained?\nThe version number you see in the requirements file output is obtained using the built-in `importlib` library. Therefore, the package *must be installed* in the environment being used to run `preqs`.\n\n- By design, we do *not* use PyPI to obtain version numbers as this practice usually involves assuming the latest version - whereas this may not be the case for your project.\n- Any packages which are known to be imported by the project, and yet do not appear in the requirements file, *are likely not installed* in the environment. Run `preqs` with the `--print` flag to observe any packages which are imported for which the version number could not be obtained. These 'unknown version' packages are (currently) ignored when the requirements file is written.\n\n### I don't see a specific package in the requirements file.\nRefer to the *How is the version number obtained?* question.\n\n### Why should I not just use `pip freeze`?\nMany online 'tutorials' for generating a requirements file say to use `pip freeze` and redirect the output to a file called `requirements.txt`. However, this is not good practice for the following reasons:\n\n- *All* of the packages installed in your development environment will be listed in the requirements file. This may include some (or many) packages which your project does not require, thus bloating the end-user's installation and thereby cluttering their environment. Or, the packages you have in your environment, although not used by the project, may be out-of-date; causing the end-user to be forced to install out-of-date packages.\n- A true requirements file should contain *only* those packages which are imported and required by the project.\n- Only the packages that were installed with `pip install` will be included in the requirements file.\n\n",
"bugtrack_url": null,
"license": "GNU GPL-3",
"summary": "A simple (and fast) requirements.txt file generator.",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/s3dev/preqs",
"Repository": "https://github.com/s3dev/preqs"
},
"split_keywords": [
"build",
" development",
" requirements",
" setup",
" utilities"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e8e40cde145b0a708e4ae918b82e8507534d174ba52512eb0c1aae649f0b236c",
"md5": "bd013485f6c950a822b84a3305675022",
"sha256": "9e6452325400150d2eec98778bab78c90d2c242fd37bf7364c990fa7a16c717d"
},
"downloads": -1,
"filename": "preqs-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bd013485f6c950a822b84a3305675022",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 23086,
"upload_time": "2024-11-12T13:30:41",
"upload_time_iso_8601": "2024-11-12T13:30:41.310823Z",
"url": "https://files.pythonhosted.org/packages/e8/e4/0cde145b0a708e4ae918b82e8507534d174ba52512eb0c1aae649f0b236c/preqs-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7d9fdedb2a9ee1405233ed0110e0192f8c1688f5959cc08ad9ab6b36204e143e",
"md5": "2f85fade512b02fc13e36e1d6921095d",
"sha256": "bbb86d50f9eca994bd08e36b255b47639a643633ad9388186b29165d02eb0cb2"
},
"downloads": -1,
"filename": "preqs-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "2f85fade512b02fc13e36e1d6921095d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 42955,
"upload_time": "2024-11-12T13:30:42",
"upload_time_iso_8601": "2024-11-12T13:30:42.617093Z",
"url": "https://files.pythonhosted.org/packages/7d/9f/dedb2a9ee1405233ed0110e0192f8c1688f5959cc08ad9ab6b36204e143e/preqs-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-12 13:30:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "s3dev",
"github_project": "preqs",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "preqs"
}
JSON
