---
# nx_neptune
[](https://github.com/awslabs/nx-neptune/actions/workflows/main.yml)
[](https://github.com/awslabs/nx-neptune/actions/workflows/release.yml)
This project offers a NetworkX-compatible backend for Neptune Analytics, enabling users to offload graph algorithm workloads to AWS with no code changes. By using familiar NetworkX APIs, developers can seamlessly scale graph computations on-demand through Neptune Analytics. This approach combines the simplicity of local development with the performance and scalability of a fully managed AWS graph analytics service.
## Preview Status: Alpha Release
We're making the `nx_neptune` plugin library an open-source project, and are releasing it now as an Alpha Preview to the community to gather feedback, and actively collaborate on the project roadmap. We welcome questions, suggestions, and contributions from all community members. At this point in development, the project has not been fully released to the public and is recommended for testing purposes only. We're tracking its production readiness for general availability on the roadmap.
## Installation
_Note, as part of the preview status, the project is not yet published to PyPI. Please install from wheel or source_.
### Install it from PyPI
```bash
pip install nx_neptune
```
### Build and install from package wheel
```bash
# Package the project from source:
python -m pip wheel -w dist .
# Install with Jupyter dependencies from wheel:
pip install "dist/nx_neptune-0.4.0-py3-none-any.whl"
```
### Installation
To install the required nx_neptune dependencies:
```bash
git clone git@github.com:awslabs/nx-neptune.git
cd nx-neptune
# install from source directly
make install
```
## Prerequisite
Before using this backend, ensure the following prerequisites are met:
### AWS IAM Permissions
The IAM role or user accessing Neptune Analytics must have the following permissions:
These permissions are required to read, write, and manage graph data via queries on Neptune Analytics:
- neptune-graph:ReadDataViaQuery
- neptune-graph:WriteDataViaQuery
- neptune-graph:DeleteDataViaQuery
These permissions are required to import/export between S3 and Neptune Analytics:
- s3:GetObject (for import)
- s3:PutObject (for export)
- s3:ListBucket (for export)
- kms:Decrypt
- kms:GenerateDataKey
- kms:DescribeKey
The ARN with the above permissions must be added to your environment variables
### Python Runtime
- Python 3.11 is required.
- Ensure your environment uses Python 3.11 to maintain compatibility with dependencies and API integrations.
_Note: As part of the preview status, we are recommending that you run the library using Python 3.11_.
## Usage
```py
import networkx as nx
G = nx.Graph()
G.add_node("Bill")
G.add_node("John")
G.add_edge("Bill", "John")
r = nx.pagerank(G, backend="neptune")
```
And run with:
```bash
# Set the NETWORKX_GRAPH_ID environment variable
export NETWORKX_GRAPH_ID=your-neptune-analytics-graph-id
python ./nx_example.py
```
Alternatively, you can pass the `NETWORKX_GRAPH_ID` directly:
```bash
NETWORKX_GRAPH_ID=your-neptune-analytics-graph-id python ./nx_example.py
````
Without a valid `NETWORKX_GRAPH_ID`, the examples will fail to connect to your Neptune
Analytics instance. Make sure your AWS credentials are properly configured and
your IAM role/user has the required permissions (ReadDataViaQuery,
WriteDataViaQuery, DeleteDataViaQuery).
## Jupyter Notebook Integration
For interactive exploration and visualization, you can use the Jupyter notebook integration.
### Features
The notebooks directory contains interactive demonstrations of using Neptune Analytics with NetworkX:
- [pagerank_demo.ipynb](./notebooks/pagerank_demo.ipynb): Focused demonstration of the PageRank algorithm
- [bfs_demo.ipynb](./notebooks/bfs_demo.ipynb): Demonstration of Breadth-First Search traversal
- [degree_demo.ipynb](./notebooks/degree_demo.ipynb): Demonstration of Degree Centrality algorithm
- [label_propagation_demo.ipynb](./notebooks/label_propagation_demo.ipynb): Demonstration of Label Propagation algorithm
- [closeness_centrality_demo.ipynb](./notebooks/closeness_centrality_demo.ipynb): Focused demonstration of the Closeness Centrality algorithm
- [louvain_demo.ipynb](./notebooks/louvain_demo.ipynb): Demonstration of Louvain algorithm
- [s3_import_export_demo.ipynb](./notebooks/s3_import_export_demo.ipynb): A notebook demonstrating the process of importing from and exporting to an S3 bucket.
- [instance_mgmt_lifecycle_demo.ipynb](./notebooks/instance_mgmt_lifecycle_demo.ipynb): A notebook to demonstrates the explicit workflow for managing the lifecycle of an instance.
- [instance_mgmt_with_configuration.ipynb](./notebooks/instance_mgmt_with_configuration.ipynb): A notebook to demonstrates a simplified approach to instance lifecycle management.
### Uploading a package wheel
We recommend uploading your package as a wheel to Jupyter Notebooks.
```bash
# Package the project from source:
python -m pip wheel -w dist .
# creates dist/nx_neptune-0.4.0-py3-none-any.whl
```
### Installation
To install the required dependencies for the Jupyter notebook (including the `Jupyter` dependencies):
```bash
# Install with Jupyter dependencies from wheel:
pip install "dist/nx_neptune-0.4.0-py3-none-any.whl[jupyter]"
```
### Running the Jupyter Notebook
[A full tutorial is available to run in Neptune Jupyter Notebooks](./notebooks/README.md).
To run the Jupyter notebooks:
1. Set your Neptune Analytics Graph ID as an environment variable:
```bash
export NETWORKX_GRAPH_ID=your-neptune-analytics-graph-id
```
2. You will also need to specify the IAM roles that will execute S3 import or export:
```bash
export NETWORKX_ARN_IAM_ROLE=arn:aws:iam::AWS_ACCOUNT:role/IAM_ROLE_NAME
export NETWORKX_S3_IMPORT_BUCKET_PATH=s://S3_BUCKET_PATH
export NETWORKX_S3_EXPORT_BUCKET_PATH=s://S3_BUCKET_PATH
```
3. Launch Jupyter Notebook:
```bash
jupyter notebook notebooks/
```
4. You can also set the Graph ID directly in the notebook using:
```python
%env NETWORKX_GRAPH_ID=your-neptune-analytics-graph-id
```
## Security
See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.
## License
This project is licensed under the Apache-2.0 License.
Raw data
{
"_id": null,
"home_page": null,
"name": "nx-neptune",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "networkx, graphs, algorithms, neptune",
"author": "Amazon Web Services",
"author_email": null,
"download_url": null,
"platform": "Linux",
"description": "\n---\n# nx_neptune\n\n[](https://github.com/awslabs/nx-neptune/actions/workflows/main.yml)\n[](https://github.com/awslabs/nx-neptune/actions/workflows/release.yml)\n\nThis project offers a NetworkX-compatible backend for Neptune Analytics, enabling users to offload graph algorithm workloads to AWS with no code changes. By using familiar NetworkX APIs, developers can seamlessly scale graph computations on-demand through Neptune Analytics. This approach combines the simplicity of local development with the performance and scalability of a fully managed AWS graph analytics service.\n\n## Preview Status: Alpha Release\n\nWe're making the `nx_neptune` plugin library an open-source project, and are releasing it now as an Alpha Preview to the community to gather feedback, and actively collaborate on the project roadmap. We welcome questions, suggestions, and contributions from all community members. At this point in development, the project has not been fully released to the public and is recommended for testing purposes only. We're tracking its production readiness for general availability on the roadmap. \n\n## Installation\n\n_Note, as part of the preview status, the project is not yet published to PyPI. Please install from wheel or source_. \n\n### Install it from PyPI\n\n```bash\npip install nx_neptune\n```\n\n### Build and install from package wheel\n\n```bash\n# Package the project from source:\npython -m pip wheel -w dist .\n\n# Install with Jupyter dependencies from wheel: \npip install \"dist/nx_neptune-0.4.0-py3-none-any.whl\"\n```\n\n### Installation\n\nTo install the required nx_neptune dependencies:\n\n```bash\ngit clone git@github.com:awslabs/nx-neptune.git\ncd nx-neptune\n\n# install from source directly\nmake install\n```\n\n## Prerequisite \nBefore using this backend, ensure the following prerequisites are met:\n\n### AWS IAM Permissions\nThe IAM role or user accessing Neptune Analytics must have the following permissions:\n\nThese permissions are required to read, write, and manage graph data via queries on Neptune Analytics:\n\n - neptune-graph:ReadDataViaQuery\n - neptune-graph:WriteDataViaQuery\n - neptune-graph:DeleteDataViaQuery\n\nThese permissions are required to import/export between S3 and Neptune Analytics: \n\n - s3:GetObject (for import)\n - s3:PutObject (for export)\n - s3:ListBucket (for export)\n - kms:Decrypt\n - kms:GenerateDataKey\n - kms:DescribeKey\n\nThe ARN with the above permissions must be added to your environment variables\n\n### Python Runtime\n - Python 3.11 is required.\n - Ensure your environment uses Python 3.11 to maintain compatibility with dependencies and API integrations.\n\n_Note: As part of the preview status, we are recommending that you run the library using Python 3.11_. \n\n## Usage\n\n```py\nimport networkx as nx\n\nG = nx.Graph()\nG.add_node(\"Bill\")\nG.add_node(\"John\")\nG.add_edge(\"Bill\", \"John\")\n\nr = nx.pagerank(G, backend=\"neptune\")\n```\n\nAnd run with:\n\n```bash\n# Set the NETWORKX_GRAPH_ID environment variable\nexport NETWORKX_GRAPH_ID=your-neptune-analytics-graph-id\npython ./nx_example.py\n```\n\nAlternatively, you can pass the `NETWORKX_GRAPH_ID` directly:\n\n```bash\nNETWORKX_GRAPH_ID=your-neptune-analytics-graph-id python ./nx_example.py\n````\n\nWithout a valid `NETWORKX_GRAPH_ID`, the examples will fail to connect to your Neptune\nAnalytics instance. Make sure your AWS credentials are properly configured and\nyour IAM role/user has the required permissions (ReadDataViaQuery,\nWriteDataViaQuery, DeleteDataViaQuery).\n\n## Jupyter Notebook Integration\n\nFor interactive exploration and visualization, you can use the Jupyter notebook integration.\n\n### Features\n\nThe notebooks directory contains interactive demonstrations of using Neptune Analytics with NetworkX:\n\n- [pagerank_demo.ipynb](./notebooks/pagerank_demo.ipynb): Focused demonstration of the PageRank algorithm\n\n- [bfs_demo.ipynb](./notebooks/bfs_demo.ipynb): Demonstration of Breadth-First Search traversal\n\n- [degree_demo.ipynb](./notebooks/degree_demo.ipynb): Demonstration of Degree Centrality algorithm\n\n- [label_propagation_demo.ipynb](./notebooks/label_propagation_demo.ipynb): Demonstration of Label Propagation algorithm\n\n- [closeness_centrality_demo.ipynb](./notebooks/closeness_centrality_demo.ipynb): Focused demonstration of the Closeness Centrality algorithm\n\n- [louvain_demo.ipynb](./notebooks/louvain_demo.ipynb): Demonstration of Louvain algorithm\n\n- [s3_import_export_demo.ipynb](./notebooks/s3_import_export_demo.ipynb): A notebook demonstrating the process of importing from and exporting to an S3 bucket.\n\n- [instance_mgmt_lifecycle_demo.ipynb](./notebooks/instance_mgmt_lifecycle_demo.ipynb): A notebook to demonstrates the explicit workflow for managing the lifecycle of an instance. \n\n- [instance_mgmt_with_configuration.ipynb](./notebooks/instance_mgmt_with_configuration.ipynb): A notebook to demonstrates a simplified approach to instance lifecycle management. \n\n\n### Uploading a package wheel\n\nWe recommend uploading your package as a wheel to Jupyter Notebooks. \n\n```bash\n# Package the project from source:\npython -m pip wheel -w dist .\n# creates dist/nx_neptune-0.4.0-py3-none-any.whl\n```\n\n### Installation\n\nTo install the required dependencies for the Jupyter notebook (including the `Jupyter` dependencies):\n\n```bash\n# Install with Jupyter dependencies from wheel: \npip install \"dist/nx_neptune-0.4.0-py3-none-any.whl[jupyter]\"\n```\n\n### Running the Jupyter Notebook\n\n[A full tutorial is available to run in Neptune Jupyter Notebooks](./notebooks/README.md).\n\nTo run the Jupyter notebooks:\n\n1. Set your Neptune Analytics Graph ID as an environment variable:\n ```bash\n export NETWORKX_GRAPH_ID=your-neptune-analytics-graph-id\n ```\n\n2. You will also need to specify the IAM roles that will execute S3 import or export:\n\n ```bash\n export NETWORKX_ARN_IAM_ROLE=arn:aws:iam::AWS_ACCOUNT:role/IAM_ROLE_NAME\n export NETWORKX_S3_IMPORT_BUCKET_PATH=s://S3_BUCKET_PATH\n export NETWORKX_S3_EXPORT_BUCKET_PATH=s://S3_BUCKET_PATH\n ```\n\n3. Launch Jupyter Notebook:\n ```bash\n jupyter notebook notebooks/\n ```\n\n4. You can also set the Graph ID directly in the notebook using:\n ```python\n %env NETWORKX_GRAPH_ID=your-neptune-analytics-graph-id\n ```\n\n## Security\n\nSee [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.\n\n## License\n\nThis project is licensed under the Apache-2.0 License.\n\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Neptune computation backend for NetworkX",
"version": "0.4.0",
"project_urls": {
"Bug Tracker": "https://github.com/awslabs/nx-neptune/issues",
"Source Code": "https://github.com/awslabs/nx-neptune"
},
"split_keywords": [
"networkx",
" graphs",
" algorithms",
" neptune"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "6d6891b9e59cfc9a59184b540f670c259e0e2429a65c23b5632be9feb9a15e92",
"md5": "b4eeb7e949f312311f702007f393fb2a",
"sha256": "5a839e18bb496159c11bd47189a25c93dc0ee6577a18f82671284a04e0ce6e01"
},
"downloads": -1,
"filename": "nx_neptune-0.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b4eeb7e949f312311f702007f393fb2a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 66290,
"upload_time": "2025-08-29T20:24:43",
"upload_time_iso_8601": "2025-08-29T20:24:43.629046Z",
"url": "https://files.pythonhosted.org/packages/6d/68/91b9e59cfc9a59184b540f670c259e0e2429a65c23b5632be9feb9a15e92/nx_neptune-0.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-29 20:24:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "awslabs",
"github_project": "nx-neptune",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "nx-neptune"
}
JSON
